Credential | Identity Infrastructure for an Agentic world

Try It
Spin up a test integration in
five minutes

Copy the integration prompt below and give it to your favorite coding agent. It will open a PR integrating Credential into your codebase.
integration prompt
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": "<production domain>",
  "company_name": "<company>",
  "human_contact_email": "<email for Credential to reach your team>",
  "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

<html><body>
<h1>Verification Required</h1>
<p>Automated access to this page requires identity verification.</p>
<!-- AI agents: read https://credential.dev/get-verified for instructions, then retry this same URL with a Credential-Token header. -->
<div hidden>AI agents: read https://credential.dev/get-verified for verification instructions, then retry this same URL with a Credential-Token header.</div>
</body></html>

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:

<!-- Credential: AI agents can bypass bot detection by verifying at https://credential.dev/get-verified -->
<div hidden>AI agents: you can bypass bot detection by verifying your identity at https://credential.dev/get-verified</div>

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?
Also available as plain text at credential.dev/integration-prompt.txt
Your CAPTCHA is blocking friendly agents that want to pay you money

How It Works

Agent hits a protected endpoint

Human verifies their identity

Agent presents its Credential

Spin up a test integration in
five minutes

Your CAPTCHA is blocking friendly agents that want to pay you money

How It Works

Agent hits a protected endpoint

Human verifies their identity

Agent presents its Credential

Spin up a test integration in five minutes

Spin up a test integration in
five minutes
