eeID Identification Service API (1.1.0)

This API provides endpoints for managing authentication tokens and handling identification requests. The authentication mechanism is based on OAuth2, using a token-based approach to secure access to the identification requests. Clients must obtain a token by providing valid credentials to access the protected resources.

The token has a limited lifespan and will expire after 120 seconds. Clients should handle token expiration and generate a new one as necessary.

When an identification request is created with claims_required, eeID compares the authenticated user's identity against those claims. Authentication success is separate from claims match:

• A request becomes completed when the end-user successfully authenticates, even if some claims do not match.
• Check claims_matched, mismatched_claims, and claims_comparison_errors on completed requests to see the comparison outcome.
• Your service is responsible for deciding how to handle mismatches (for example manual review, approval, or rejection).
• Proof of identity (POI) is generated and the completion webhook is sent for all successfully authenticated requests, regardless of claim match.
• After the first successful authentication, the identification link expires. The end-user cannot use the same link to retry; create a new request if another identification is needed.

For document-based identification, the result object may also include country, id_number, and document_number. These fields are not present for other authentication methods. The sub claim always comes from OIDC userinfo.

Endpoint for obtaining authentication token.

Endpoints for managing identification requests.

A Webhook to receive notification about successful completion of created Identification Request. To be able to receive notification, this API needs to be implemented and deployed by the client. The webhook URL is configured by the client in the eeID manager when creating the identification service and must contain the path eeid/webhooks/identification_requests.

To ensure the integrity and authenticity of the request, an HMAC signature is included in the request header. Clients must verify this webhook request as follows:

Verifying the HMAC Signature:

• Upon receiving the webhook, extract the X-HMAC-Signature from the request headers.
• Recreate the HMAC signature with the received payload and your client_secret.
• Compare the recreated signature with the signature from the header. If they match, the request is verified as authentic.
• Example in Ruby:

  received_signature = request.headers['X-HMAC-Signature']
  expected_signature = OpenSSL::HMAC.hexdigest('SHA256', secret_key, request.raw_post)
  if received_signature != expected_signature
    raise "Invalid HMAC signature"
  end
  

The event is considered acknowledged if the endpoint responds with a successful status code (200, 201 or 204) within 10 seconds. Any other status code or a lack of response is treated as a delivery failure, leading to up to 3 retries. This may result in the same event being delivered multiple times in exceptional cases.