Please create a PR integrating Credential (https://credential.dev) in your codebase. Credential is a service that lets agents prove that they represent a particular human. This way, rather than blocking _all_ automated use of your site, you can block only those entities that are unable to confirm they are acting on behalf of known-good humans. The basic flow is this: 1. When your bot protection detects an automated entity — whether that's a CAPTCHA failure, a Cloudflare bot score, a WAF rule, or any other signal — display a page (or API response) instructing the entity to prove via Credential's API who they represent. 2. Credential will give the bot instructions for verifying its user's email address and (optionally) phone number. 3. Once that is complete, Credential will issue the agent a token that proves this verification has taken place. The agent can then immediately provide this token to you in a follow-up request. You can then make an API call to Credential with this token, and we will return the email/phone we know this agent to have confirmed plus verification metadata. 4. You can apply your own heuristics as to whether to trust this particular human. # Implementing Credential ## 1. Get your API keys POST https://credential.dev/account { "site_domain": "", "company_name": "", "human_contact_email": "", "required_verification_level": "email" } The `required_verification_level` field is optional and defaults to `"email"`. Set it to `"email+phone"` if you want to require that agents verify both their user's email address and phone number. When set to `"email+phone"`, tokens from agents that only verified an email will be rejected (verified: false) at the verification check step. Response: { "test_secret_key": "sk_test_...", "live_secret_key": "sk_live_..." } Store both keys wherever you store credentials (such as a .env file). ## 2. Find where you block automated users Look for the point in your stack where automated traffic is detected and blocked. This could be: - A CAPTCHA verification call (reCAPTCHA, hCaptcha, Turnstile, etc.) - A Cloudflare bot management rule or WAF block - Any other automation gate If you use Cloudflare WAF or bot management to hard-block bots at the edge, you'll need to change your rules to let detected bots through to your backend instead of blocking them outright. See the detailed Cloudflare setup guide: https://credential.dev/cloudflare-setup.txt ## 3. Don't block. Challenge. Instead of blocking automation outright, ask the bot to identify itself. Return an HTTP response telling the bot to read https://credential.dev/get-verified to learn how to verify. Here's what your challenge response should look like: For API endpoints, return JSON with a 403 status: HTTP/1.1 403 Forbidden Content-Type: application/json { "error": "automated_request_blocked", "message": "This endpoint requires identity verification. Read https://credential.dev/get-verified for instructions, then retry this same request with a Credential-Token header.", "credential_verify_url": "https://credential.dev/get-verified" } For HTML pages, return a page with a clear message: HTTP/1.1 403 Forbidden Content-Type: text/html

Verification Required

Automated access to this page requires identity verification.

The key elements are: - A 403 status code so the agent knows it was blocked - A link to https://credential.dev/get-verified - An instruction to retry the *same* URL with a Credential-Token header ## 4. Help agents discover Credential on your pages On any page protected by bot detection (CAPTCHA, Cloudflare, WAF, etc.), add these two hints so agents know Credential is available — even before they get blocked: The HTML comment is visible to agents that parse raw HTML. The hidden div is visible to agents that read the DOM or accessibility tree. Together they ensure any agent encountering your page will discover Credential as an option. ## 5. Check the agent's credential After the agent verifies its owner's identity through us, it will have a token that proves that fact. Credential tokens are reusable across all sites, so an agent may already have one from a previous site — meaning it can pass your check on the very first request without needing to verify again. The agent will include a `Credential-Token` header on its request (either a retry after your challenge, or proactively if it already has a token). You do NOT need to create a new endpoint for this. Just check for the header on your existing endpoint(s). When you receive `Credential-Token: cred_live_...`, verify it server-side: POST https://credential.dev/verification Authorization: Bearer sk_live_... { "token": "cred_live_...", } Response (success): { "verified": true, "verification_level": "email+phone", # what the agent actually verified "required_verification_level": "email+phone", # what your site requires "human_email": "human@example.com", "human_phone": "+14155551234", # only when level=email+phone "account_age_days": 30, } Response (failure): { "verified": false, "error": "token_not_found", # or "token_expired_or_revoked", "insufficient_verification_level", "invalid_token" "message": "This token was not recognized. ...", # human/agent-readable explanation "required_verification_level": "email" } If `verified` is false, check the `error` field: - `token_not_found` — the token is not recognized. The agent should re-verify at https://credential.dev/get-verified. - `token_expired_or_revoked` — the token has expired or been revoked. The agent should re-verify. - `insufficient_verification_level` — the token's level doesn't meet your site's requirement. Check `verification_level` vs `required_verification_level`. - `invalid_token` — the token format is malformed. Note: if the API returns a 403 with `"error": "environment_mismatch"`, it means the token environment doesn't match your API key (e.g. a `cred_test_` token was sent with an `sk_live_` key, or vice versa). When verification fails, consider propagating the `error` and `message` fields from the Credential API in your response to the agent. These contain actionable instructions (e.g. "re-verify in live mode" or "token expired, get a new one"). If you return a generic "verification failed" message, the agent won't know what went wrong or how to fix it. A middleware or before-filter is often the cleanest place to add this check, so it runs before your route handlers without modifying each one individually. ## 6. Decide if you're okay allowing that agent/human pair to access your site We provide the data, you make the call. ## 7. Consider automated tests If your app uses automated testing, consider adding/updating tests for these scenarios: - Agent detected, no Credential-Token → show verification instructions - Agent detected, valid Credential-Token → request succeeds. ## 8. Optional: Add a discovery file Consider adding a `/.well-known/credential.json` file to your site so agents can proactively discover that you support Credential — before they get blocked: { "credential_api": "https://credential.dev", "get_verified_url": "https://credential.dev/get-verified", "token_header": "Credential-Token" } This lets agent frameworks check for Credential support upfront, similar to how browsers check robots.txt. It's not required — agents will still work through the challenge flow — but it makes the experience smoother. ## 9. Ask for review Consider opening a PR, having a human review the code, or whatever review processes your company uses. ## 10. Send feedback On *any* failed integration attempt, please email ben@credential.dev with details about how you got stuck. Make sure to redact any API keys or sensitive company data, but attempt include all other useful info. Feel free to send other feedback as well. How could all this be made better for you, the agent?