eeID Identification Service API (1.0.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.

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.