> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# Check Credentials API Guide

> Reference for the Check Credentials API, including environments, authentication, error handling, and the Check Credentials endpoint.

This API returns whether a user has a valid and active credential required for a given policy. For example, passing in an IAL2 policy scope returns whether the user is verified at that level or not.

## Environments

IDMe provides two environments:

#### Sandbox

`https://api.idmelabs.com`

#### Production

`https://api.id.me`

**Sandbox**

* Used for development, connectivity, and user-acceptance testing
* Test credentials can be used for testing various scenarios
* Credentials are separate from the production environment

**Production**

* Used for production-level integration
* Only real credentials can be used (no test credentials)
* Credentials are separate from the sandbox environment

## Authentication

API authentication works using a shared secret token generated with a strong cryptographic algorithm. This token must be handled and stored securely.

All API calls require the token to be passed in the request, using either a query parameter or a Bearer token authorization header:

**`Query parameter`**

```curl Query parameter
?access_token=<token>
```

**`Authorization header`**

```curl Authorization header
Authorization: Bearer <token>
```

The API token only grants access to the endpoints listed in this document, and access is constrained to users tied to the partner through a valid and active credential license. If no credential license exists, or the license has expired, the request is rejected with an appropriate error message.

> **Note**
>
> API tokens are provided out-of-band from the technical integration.

## Errors and HTTP status codes

Common HTTP status codes separate failure scenarios by type. Some responses also include a specific error code and human-readable message:

```json
{
  "code": "<code>",
  "message": "<message>"
}
```

### 401 - Invalid authentication credentials

| Code | Description                                    |
| ---- | ---------------------------------------------- |
| 110  | Access token is invalid or missing             |
| 120  | Attempting to access an invalid resource       |
| 130  | Access token is not tied to a valid policy     |
| 140  | Integration credentials are invalid or missing |
| 160  | Invalid or missing event identifier            |
| 180  | Resource license is missing or invalid         |
| 190  | Setup identifier is missing or invalid         |

### 403 - Credentials do not have access to given resource

| Code | Description                                |
| ---- | ------------------------------------------ |
| 111  | Access token has been revoked              |
| 112  | Access token has expired                   |
| 121  | Attempting to access a suspended resource  |
| 122  | Attempting to access a revoked resource    |
| 131  | Access token is tied to an inactive policy |
| 141  | Integration credentials are disabled       |
| 181  | Resource license has expired               |

### Other status codes

| Status | Description                      |
| ------ | -------------------------------- |
| 404    | Accessed resource does not exist |
| 422    | Invalid or missing parameters    |
| 429    | Rate limit exceeded              |
| 500    | Internal service errors          |

## Validation errors

HTTP status code 422 is reserved for input validation errors. The response contains an object where the keys correspond to input parameter names and the values are error messages.

The key can also be `base`, indicating a higher-level, process-related error — for example, an SMS-based code that has already been used or has exceeded the retry threshold.

**`Example - field error`**

```json Example - field error
{
  "errors": {
    "delivery": "Delivery can't be blank"
  }
}
```

**`Example - field and base error`**

```json Example - field and base error
{
  "errors": {
    "code": "Code can't be blank",
    "base": "Confirmation code is not valid. Please request a new code and try again."
  }
}
```

> **Recommended handling**
>
> Treat errors on the `base` key as overall, general errors shown in a notification banner at the top of the page. Show individual field-related errors below the corresponding field. This mirrors the structure of the API response in the UI.

## Check credentials

POST   /api/auth/v1/credentials/:uuid/check

Returns whether a user has a valid and active credential required for a given policy. For example, passing in an IAL2 policy scope returns whether the user is verified at that level or not.

### Parameters

| Name    | Description                                                                         | Type   | Required |
| ------- | ----------------------------------------------------------------------------------- | ------ | -------- |
| `uuid`  | Unique identifier for the user (passed in the URL)                                  | string | Yes      |
| `scope` | Policy handle to check against (same value passed as the SAML `AuthnContext` value) | string | Yes      |

### Response

| Field      | Description                                  | Type    |
| ---------- | -------------------------------------------- | ------- |
| `verified` | Whether the user has the required credential | boolean |

**`Response body`**

```json Response body
{
  "verified": true
}
```