REST API details

Relying Party API is exposed over a REST interface. All messages are encoded using UTF-8. All requests only support HTTP/1.1, as described in RFC 2616.

HTTP status codes

Normally, all positive responses are returned with HTTP status code 200.

In some cases, 400 series error codes are used, those cases are described per request.

All 500 series error codes indicate some kind of fatal server error.

In addition to standard HTTP error codes the following RP API specific codes are used:

  • 471 - No suitable account of requested type found, but user has some other accounts.

  • 472 - Person should view Smart-ID app or Smart-ID self-service portal now.

  • 480 - The RP API client is too old and not supported any more.

  • 580 - System is under maintenance, retry again later.

Idempotent behaviour

Whenever an RP session creation request (POST to certificatechoice/, signature/, authentication/) is repeated inside a given timeframe with exactly the same parameters, session ID of an existing session can be returned as a result.

This allows to retry RP POST requests in case of communication errors.

Retry timeframe is 15 seconds.

When the caller wants, it can override the idempotent behaviour inside this timeframe using an optional nonce parameter present for all POST requests. Normally, that parameter can be omitted.

Interface authentication

RP API clients are authenticated based on their originating IP-address and relyingPartyUUID protocol parameter combinations.

When authentication fails, server responds with HTTP error 401.

relyingPartyName request field is case insensitive, must match one of the names configured for the calling RP. The names are limited to 32 bytes in UTF-8 encoding and are displayed to the user in the Smart-ID application.

API client must ignore unknown names (fields) in JSON response object

The Smart-ID service reserves the right to add new fields into responses of the current RP API version.

Therefore, the RP must ignore unknown names (fields) in JSON response objects at any location within the JSON structure.

RP API endpoint authentication

This section will be merged with Secure Implementation Guide.

It is essential that RP client performs all the required checks when connecting to the Smart-ID RP API HTTPS endpoint, to make sure that the connection endpoint is authentic and that the connection is secure.

This is required to prevent Man-in-the-middle (MITM) attacks for the authentication and signature protocols.

The RP must perform the following checks:

  1. Verify the HTTPS connection and the TLS handshake is performed with a secure TLS ciphersuite.

  2. Verify the X.509 certificate of the HTTPS endpoint belongs to the well-known public key of the Smart-ID API. The RP must implement HTTPS key (or certificate) pinning.

  3. Verify the X.509 certificate of the HTTPS endpoint is valid (not expired, signed by trusted CA and not revoked).

In case the RP fails to verify the connection is genuine and secure an attacker might be able to launch a AITM attack on the connection and either login as the user or have the user sign a forged document.