canonical: https://jentic.com/apis/id.me/id-me

# ID.me API

Jentic publishes the only available OpenAPI specification for ID.me API, keeping it validated and agent-ready. ID.me provides identity verification used by US federal and state government agencies, healthcare networks, and commercial brands to confirm identity and group membership for benefits like military, first responder, and student discounts. The API exposes an OAuth 2.0 authorization flow plus endpoints to fetch verified user info and check group membership. Five endpoints cover the full integration surface: authorize, token, userinfo, list groups, and verify a group affiliation.

## For AI agents

Run an OAuth 2.0 identity verification flow with ID.me, fetch verified user attributes, and confirm group affiliations such as military or student status.

## Scope

Does not handle document scanning, biometric liveness checks, or KYC anti-fraud screening - use for OAuth-based identity verification and group affiliation checks only.

## Capabilities

- Initiate an OAuth 2.0 authorization request that routes the user through ID.me identity verification
- Exchange an authorization code for an access token via `/oauth/token`
- Fetch verified user attributes - name, email, verified groups - through /userinfo
- List supported affiliation groups (military, first responder, student, teacher, nurse) via /groups
- Confirm a user's membership in a specific group through `/groups/{groupId}/verify`

## Use cases

### Group-Affiliation Discount Gating

Gate a discount or benefit behind a verified affiliation such as military, first responder, student, or nurse. The user is redirected to `/oauth/authorize`, completes ID.me verification, and the application then calls /userinfo or `/groups/{groupId}/verify` to confirm eligibility. Most checkouts integrate the flow in a few days because OAuth 2.0 patterns are well documented.

Example prompt: Redirect the user to `/oauth/authorize` with scope=military, exchange the returned code at `/oauth/token`, then call `/groups/military/verify` with the access token

### Government Benefits Login

Provide a single-sign-on for a benefits portal that requires identity proofing to NIST IAL2 levels. The OAuth 2.0 flow routes through ID.me's verification, and on completion /userinfo returns the verified identity payload that the portal uses to provision the session.

Example prompt: Build the `/oauth/authorize` URL with the verified-identity scope, capture the callback code, and exchange it for an access token to call /userinfo

### Healthcare Worker Verification

Verify that a portal visitor is a healthcare worker before granting access to clinician-only resources or pricing. After OAuth, the application calls `/groups/{groupId}/verify` with the nurse or medical-professional group ID and gates access based on the boolean response.

Example prompt: After OAuth, call `/groups/nurse/verify` with the access token and grant portal access only when the response confirms membership

### AI Agent Identity Check

An onboarding agent uses Jentic to find ID.me operations matching 'verify user identity', orchestrates the OAuth 2.0 redirect, and uses the returned token to call /userinfo. The agent then routes the user through the appropriate downstream workflow based on verified attributes - without the developer hand-coding the OAuth dance.

Example prompt: Use Jentic search 'verify user identity', load the ID.me /userinfo schema, and execute it with the user's access token to retrieve verified attributes

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/oauth/authorize` | Start the OAuth 2.0 authorization flow with identity verification |
| POST | `/oauth/token` | Exchange an authorization code for an access token |
| GET | `/userinfo` | Fetch the verified user's profile and group affiliations |
| GET | `/groups` | List supported affiliation groups |
| GET | `/groups/{groupId}/verify` | Confirm the user's membership in a specific group |

## Key resources

- **OAuth** — Authorization and token endpoints for the identity verification flow
- **User Info** — Verified user attributes returned after successful authorization
- **Groups** — Affiliation groups (military, first responder, student, etc.) and per-user verification

## Why Jentic

- **Setup:** Wiring the ID.me API by hand means running its OAuth2 authorize and token exchange and mapping its userinfo and group verification routes yourself. Through Jentic you install once, import the ID.me API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** ID.me puts the group id in the URL path (`/groups/{groupId}/verify`), so a rule can pin your agent to verifying membership for one group. You choose the operations it may call, so reading full user profile info is not included unless you add it.
- **Credential handling:** Your ID.me OAuth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'verify a user's group affiliation' or 'read a verified user's info', and Jentic returns the matching ID.me operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 API** — General-purpose identity platform with OAuth, SSO, and MFA but no built-in affiliation verification
- **Onfido API** — Document and biometric identity verification used for KYC and onboarding
- **Okta API** — Workforce and customer identity platform that can broker ID.me as a federated provider

## FAQ

### Why is there no official OpenAPI spec for ID.me API?

ID.me does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ID.me API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ID.me API use?

The ID.me API uses OAuth 2.0. Applications redirect users to `/oauth/authorize`, then exchange the returned code at `/oauth/token` for an access token, which is sent as a bearer credential on subsequent calls to /userinfo and /groups. Through Jentic, client secrets are stored encrypted in your Jentic One instance and injected at execution time.

### Can I verify a user's military status with the ID.me API?

Yes. After the OAuth flow completes, call GET `/groups/military/verify` with the user's access token to receive a boolean confirmation of military affiliation. The same pattern works for first responder, nurse, teacher, and student groups exposed by GET /groups.

### What are the rate limits for the ID.me API?

ID.me applies per-application rate limits negotiated as part of partner onboarding rather than a public ceiling. The OpenAPI spec does not encode the exact limits because they are contract-specific. Design agents to handle 429 responses with backoff and to cache /userinfo results for the duration of a session.

### How do I run an ID.me identity check through Jentic?

Run pip install jentic and import the SDK, then await client.search('verify user identity') to discover the ID.me /userinfo operation. After the OAuth redirect completes in your app, load the schema and execute with the user's access token. Run Jentic One, the self-hosted execution layer, for an API key.

### Is the ID.me API free?

ID.me operates on a partner agreement model. Government and not-for-profit relying parties are typically subsidised, while commercial brands offering group discounts pay per verified user. Pricing is negotiated directly with ID.me - the OpenAPI spec describes only the request and response shapes.

### Can I limit what my agent is allowed to do with the ID.me API?

Yes. Because you run Jentic One yourself, your own rules decide which ID.me operations the agent may call and which OAuth credentials it may use. Since ID.me puts the group in the URL path at `/groups/{groupId}/verify`, you can pin the agent to verifying membership for a single group, such as military or student. And because you pick the operations, reading a full user profile through /userinfo is off limits unless you explicitly allow it.