Check Credentials API

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

ID.me provides two environments:

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:

$
?access_token=<token>

$
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.

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:

1
{
2
  "code": "<code>",
3
  "message": "<message>"
4
}

401 - Invalid authentication credentials

403 - Credentials do not have access to given resource

Other status codes

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.

1
{
2
  "errors": {
3
    "delivery": "Delivery can't be blank"
4
  }
5
}

1
{
2
  "errors": {
3
    "code": "Code can't be blank",
4
    "base": "Confirmation code is not valid. Please request a new code and try again."
5
  }
6
}

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

Response

1
{
2
  "verified": true
3
}