Documentation

Suspensions & Reinstatements API

Here you can find API specifications for the ID.me Events & Audit logging service. This service contains an API with end points that enables querying and retrieval of event logs for suspensions/reinstatements based on a timestamp. Details around the service's environments, authentication mechanism and list of events available are described here.

Prerequisites

Before getting started with the Suspensions/Reinstatements API, be sure you have complete the full integration in sandbox (to test) and production.

This API only returns the user’s uuid, therefore, to store the uuid with the account on their side in order to associate suspension and reinstatement events from ID.me.

  • Ensure your integration is complete
  • Confirm your are storing the uuid on your user records

Step 1. Generate OpenSSL x509 Certificate

In most cases, you may be unable to send over .cer, .crt, and .pem files via email, even if they are compressed with a .zip file.

You can use Virtru to exchange sensitive files, API credentials and information via email with your ID.me account team.

  • Generate x509 certificate
  • Securely send certificate via encrypted email

Once submitted, please contact your ID.me account team to confirm we have received the appropriate files.

Step 2. ID.me Generates API Key

API authentication works using a shared secret key thats generated using a strong cryptographic algorithm. Please make sure this key is kept safe. To successfully authenticate, the shared secret needs to be Base64 encoded and passed as an Authorization header, along with the ID.me prefix.

The API key should be sent using Virtru.

API Key Request

Contact your Solution Consultant to generate a sandbox API key, you can request a production API key once you have successfully integrated and tested in your development environment.

The API key be scoped only for the following endpoints:

/api/v1/suspensions/daily /api/v1/suspensions/weekly

  • Using Postman, confirm the API key connects and successfully returns a HTTP 200 OK

Step 4. Execute Data File Requests

The general HTTP authentication framework, RFC 7235, defines a protocol which can be used by a server to challenge a client request, and by a client to provide authentication information. HTTP provides a general framework for access control and authentication by requiring that the server request a user name and password from the web client and verify that the user name and password are valid by comparing them against a database of authorized users.

A client that wants to authenticate itself with the server can then do so by including an Authorization, user name and password request header with the credentials. In the case of a HTTP Basic Authentication, the exchange must happen over an HTTPS (TLS) connection to be secure.

CURL Example

curl -X POST -d "timestamp=2023-10-15T12:58:10.963Z

Endpoint

/api/v1/suspensions/daily OR /api/v1/suspensions/weekly

HTTP Request Method

POST

Request Header

Authorization: ID.me <base64-encoded-key>

Parameters

Name Description
timestamp UTC date for the day/week of the events

Step 5. ID.me Encrypts JSON Data File

A random session key and initialization vector is generated using OpenSSL. Response data is encrypted with the session key. Session key is encrypted with your public key certificate. Encrypted session key, encrypted data and the IV are Base64 encoded. Encoded data is returned encoded into JSON.

Step 6. Retrieve Response Headers

The response will also contain the "Key" and "IV" headers, which will be used to decrypt the file contents. Both of these headers are Base64 encoded, and the "Key" has been encrypted using your public key. To decrypt the file, first decode the "Key" and "IV" values, then decrypt the "Key" using your private key. Finally, use the decrypted Key and IV to decrypt the file using AES- 256-CBC algorithm.

Note: The padding user for AES-256-CBC is PKCS1_PADDING

If the file isn't immediately available, a process will be started to generate the file for the time interval requested by the timestamp.

  • Receive the following values in the response header:
    • X-Payload-Key
    • X-Payload-IV
  • Base64 decode each value

Example Response Header

{ "X-Payload-Key": "<Base64 encoded AES-256-CBC Key>", "X-Payload-IV": "<Base64 encoded AES-256-CBC Initialization Vector>" }

Example Decoded X-Payload-Key

b1121fc7af68ce1f63f51a0a780ee37bb7c04c67bf1964d5f81ea30e061b55a709ab677ea655ca93b514822fc00c2c58522b929e382e042a52d060c26f40e86665dd478bd6748833c32083049bae0a31269c8e6e6bf45dd12bb203cdc3652cdda17dc84d42186dcf5d94aeac145305e74c6b347d3352b35469a722de00fb4f44fc9e7d0b0bcaff58f8e6a8be72f6775fc704e6f8d2b03caf98a3c07bd7dc29cd86fe0e38bf4a3e90329f8a3c87af42c785c33d784909b49453267793c49ad4db18ad3dd4743cecde11630e9e819e8bf927c548e8550dcc6365531dab57b8c39116b5e26fe23a67c1f8cb8f4ad15fee7185ebb3c8169ce9d66107bd128cb81ca1

Example Decoded X-Payload-IV

e0d4f0f8f2b93752f9a3ee1285cde247

Step 7. Decrypt JSON Payload

Read the response header, the decodes the Base64 encoded values for the header information. Decrypts the encrypted session key using your private key. Uses the decrypted session key and the IV to decrypt the data payload.

Protected REST endpoints can be accessed by making HTTP requests with the access token for a given user. The ID.me server will validate the access token to ensure it has not expired and that its scope covers the requested resource.

  • Decrypt the JSON payload using their session key, IV and private key

Example Decrypted JSON Payload

{ "events":[ { "action":"suspend", "identifier":"34671240855d407eab94f5851a2f899a", "created_at":"2021-06-10 16:55:25 UTC", "reason": { "code": "", "desc": "" } } ] }

Step 8. Parse the JSON Response

Parsing the JSON response correctly is key to implementing a scalable solution. How to retrieve data from the JSON response can determine It is best practice to:

  • Store the user’s uuid during each authentication and authorization
  • Index values using the identifier within the event array
  • Store the raw JSON responses for auditing purposes
  • You should leverage the identifier to look up users in record by their ID.me uuid from their initial interaction with a your application
  • Leverage the uuid value as a foreign key on transactions to track ID.me user activity across your application ecosystem
  • When code=PROCESSING is returned, you should briefly poll that request and retry until:
    • A HTTP 200 OK is returned
    • A X-Payload-Key and X-Payload-IV are present in the response headers

Top level keys

Furnished upon request.