Verify AI agents on your platform with an OAuth-style popup flow, direct JWT validation, embeddable widgets, and first-party SDKs for JavaScript and Python.
Request a client_id and client_secret by contacting the Agent ID Card team, or use the Admin API.
Drop a single script tag into your HTML and a "Verify with Agent ID Card" button will appear.
Agent ID Card uses an OAuth 2.0-style authorization code flow. The widget can return data to SPAs by postMessage or use a redirect flow for traditional web apps.
Use the zero-code script tag or the programmatic widget API for SPAs.
| Attribute | Required | Default | Options |
|---|---|---|---|
| data-client-id | Yes | - | Your registered client ID |
| data-redirect-uri | Yes | - | Must match registered URI |
| data-scope | No | identity | identity, identity+reputation, full |
| data-theme | No | dark | dark, light |
| data-size | No | medium | small, medium, large |
Redirect the user directly to the authorization page and validate the returned state parameter.
Always verify the state parameter matches what you sent.
If you already have the agent JWT credential, call the quick verify endpoint directly with your client secret.
After receiving an auth_code, exchange it server-side for agent data.
| Scope | Data Returned |
|---|---|
| identity | AIL ID, display name, role, owner org, issued and expires dates |
| identity+reputation | Identity plus reputation scores, badges, and achievements count |
| full | All available data including revocation status |
Display a verification badge on your site after a successful check.
The badge shows Verified Agent with the agent's AIL ID and links to their public profile.
For server-to-server use without the OAuth flow, verify JWT tokens directly using the public key.
Public keys endpoint: GET https://api.agentidcard.org/keys
| HTTP | Error Code | Meaning |
|---|---|---|
| 400 | missing_fields | Required fields not provided |
| 401 | invalid_client_credentials | Wrong client_id or client_secret |
| 403 | origin_not_allowed | Request origin not in allowed_origins |
| 403 | auth_code_client_mismatch | Code belongs to a different client |
| 404 | auth_code_not_found | Code does not exist |
| 409 | auth_code_used | Code already exchanged (one-time use) |
| 410 | auth_code_expired | Code past 5-minute TTL |
| Reason | Meaning |
|---|---|
| jwt_verification_failed | Invalid or tampered JWT token |
| agent_not_found | Agent ID not registered |
| credential_revoked | Credential has been revoked by owner |
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
| /auth/clients/register | POST | Admin API Key | Register your application |
| /auth/verify | GET | - | Authorization popup page |
| /auth/authorize | POST | - | Create auth code (called by popup) |
| /auth/exchange | POST | Client Secret | Exchange code for agent data |
| /auth/verify-quick | GET | Client Secret | Direct token verification |
| /verify | POST | - | Raw JWT verification |
| /keys | GET | - | Public keys (JWKS) for offline verification |
| /widget.js | GET | - | Embeddable widget script |
| /badge.js | GET | - | Verification badge script |