Skip to main content

Implement with the Signicat REST API

This guide shows you how to authenticate end-users with Czech Bank iD, using the Signicat Authentication REST API with redirect flow.

Want to learn more?

To learn more about the Signicat Authentication REST API before integrating, see:

Prerequisites​

  1. Follow the steps on the Set up Czech Bank iD page to establish a connection with Czech Bank iD.

  2. Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see Connect to Signicat APIs Quick start guide.

    Ensure that you set the Authentication REST API permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide.

    Learn more about the Signicat Authentication REST API

Redirect flow​

This guide shows how to set up authentication using the redirect flow. The redirect flow allows you to pass an authorization URL to your end-users that they can open in a browser to follow an identity verification flow with Czech Bank iD.

1. Create a session​

Request​

To create a session using the Authentication REST API, you need to send a POST request to the Create a new session endpoint.

Enpoint URL: https://api.signicat.com/auth/rest/sessions

For example, you can build your request like this:

POST /auth/rest/sessions HTTP/1.1
Host: api.signicat.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <ACCESS_TOKEN>
Content-Length: 735

{
  "flow": "redirect",
  "requestedAttributes": [
    "idpId",
    "name",
    "firstName",
    "lastName",
    "middleName",
    "dateOfBirth",
    "gender",
    "placeOfBirth",
    "countryOfBirth",
    "nationality",
    "address", 
    "nin",
    "phoneNumber", 
    "email",
    "eighteenOrOlder",
    "maritalStatus",
    "bankidCzTitlePrefix",
    "bankidCzTitleSuffix",
    "bankidCzPep",
    "bankidCzLimitedLegalCapacity",
    "bankidCzPaymentAccounts",
    "bankidCzUpdatedAt",
    "bankidCzIdCard"
  ],
  "callbackUrls": {
    "success": "https://example.com/success",
    "abort": "https://example.com/abort",
    "error": "https://example.com/error"
  },
  "allowedProviders": [
    "bankid-cz"
  ],
  "language": "en"
}

Note the following fields in the payload of the request:

For more information about the "Create a new session" endpoint, see the API Reference description.

AML verification

Czech Bank iD offers flows for compliance with Anti-Money Laundering (AML) laws and regulations. Learn more about the data attributes for AML in the Attributes reference overview page.

Response​

After you create a session, you receive a response with a summary of your request, a unique ID for the process and an authenticationUrl.

Here is an example response:

{
    "id": "c99e17e2-b124-f549-a88c-408f8e555d31",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "abort": "https://example.com/abort?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "error": "https://example.com/error?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31"
    },
    "allowedProviders": [
        "bankid-cz"
    ],
    "language": "en",
    "flow": "redirect",
    "requestedAttributes": [
        "address",
        "bankidCzIdCard",
        "bankidCzLimitedLegalCapacity",
        "bankidCzPaymentAccounts",
        "bankidCzPep",
        "bankidCzTitlePrefix",
        "bankidCzTitleSuffix",
        "bankidCzUpdatedAt",
        "countryOfBirth",
        "dateOfBirth",
        "eighteenOrOlder",
        "email",
        "firstName",
        "gender",
        "idpId",
        "lastName",
        "maritalStatus",
        "middleName",
        "name",
        "nationality",
        "nin",
        "phoneNumber",
        "placeOfBirth"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2025-04-30T12:43:22.0805822+00:00"
}

2. End-user authentication​

Now, your application can redirect the end-user to the authenticationUrl you obtained in the response. This is a unique URL that allows the end-user to perform authentication in the context of the session you just created.

User journey​

By opening the authentication URL in the browser, end-users can follow an authentication flow with Czech Bank iD. You can preview what the flow looks like in the Test it out page.

When the end-user completes the authentication flow, they are automatically redirected to the callbackUrls according to the outcome of the authentication.

3. Get the session status​

During the authentication process, you can monitor the status of the session to track whether the flow has started, failed or completed. Responses from successful authentications contain the end-user personal data.

Request​

To get the status of a session, you need to send a GET request to the Get session status endpoint.

You can find the session id value in the response you received when you created the session.

GET /auth/rest/sessions/{SESSION_ID} HTTP/1.1
Host: api.signicat.com
Accept: application/json
Authorization: Bearer <ACCESS_TOKEN>

In the response example above, substitute the SESSION_ID with the value of the id you received in the response after creating the session. The value of the id is c99e17e2-b124-f549-a88c-408f8e555d31 so the request would be https://api.signicat.com/auth/rest/sessions/c99e17e2-b124-f549-a88c-408f8e555d31.

Response​

The response contains a status field with up-to-date information about the status of a session. Depending on the outcome of an authentication, the session can be in any of these states: CREATED, SUCCESS, ERROR, ABORT, CANCELLED, WAITING_FOR_USER, EXPIRED, INVALID. For more information about the "Get session status" endpoint, see the API Reference description.

Review the response​

When the end-user authenticates successfully, you receive a response with status: SUCCESS. Then, you can retrieve personal data of the user in the subject field of the JSON response. For example:

{
    "id": "c99e17e2-b124-f549-a88c-408f8e555d31",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31",
    "status": "SUCCESS",
    "provider": "bankid-cz",
    "subject": {
        "id": "2chXmU2kWsMJWZ4x-mCxcbiaKSkSVNDiglqp8nBIP5s=",
        "idpId": "fed17912-aa8b-4f88-8c0f-9eb2b909d07f",
        "name": "Jan Novák",
        "firstName": "Jan",
        "lastName": "Novák",
        "dateOfBirth": "1970-08-01",
        "email": "J.novak@example.com",
        "nin": {
            "value": "7008018556",
            "issuingCountry": "CZ",
            "type": "PERSON"
        },
        "placeOfBirth": "Praha 4",
        "countryOfBirth": "CZ",
        "nationality": "AT, CZ",
        "maritalStatus": "MARRIED",
        "bankidCzPep": "false",
        "bankidCzLimitedLegalCapacity": "false",
        "bankidCzPaymentAccounts": "CZ9530300000000999999998, CZ4830300000000999999971",
        "bankidCzUpdatedAt": "1622543116",
        "bankidCzIdCard": "123456789",
        "phoneNumber": "+420123456789",
        "gender": "M",
        "address": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315",
        "addressFormatted": {
            "FullAddress": "PERMANENT_RESIDENCE, Dlouhá, 2, 609, Praha, 11000, CZ, 21722315",
            "Street": "Dlouhá",
            "HouseNumber": "609",
            "City": "Praha",
            "PostalCode": "11000",
            "Country": "CZ"
        }
    },
    "callbackUrls": {
        "success": "https://example.com:443/success?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4",
        "abort": "https://example.com:443/abort?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4",
        "error": "https://example.com:443/error?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4"
    },
    "environment": {
        "ipAddress": "192.0.2.0",
        "userAgent": "userAgent"
    },
    "loa": "high",
    "allowedProviders": [
        "bankid-cz"
    ],
    "language": "en",
    "flow": "redirect",
    "requestedAttributes": [
        "address",
        "bankidCzIdCard",
        "bankidCzLimitedLegalCapacity",
        "bankidCzPaymentAccounts",
        "bankidCzPep",
        "bankidCzTitlePrefix",
        "bankidCzTitleSuffix",
        "bankidCzUpdatedAt",
        "countryOfBirth",
        "dateOfBirth",
        "eighteenOrOlder",
        "email",
        "firstName",
        "gender",
        "idpId",
        "lastName",
        "maritalStatus",
        "middleName",
        "name",
        "nationality",
        "nin",
        "phoneNumber",
        "placeOfBirth"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2025-04-30T13:15:01.9071912+00:00"
}

In the response object, you also find the eID (see provider) that the end-user chose for authentication. This can be useful when more than one eID is active in your Signicat account.

Success!

You have now completed an authentication flow with Czech Bank iD using the Signicat Authentication REST API.

UX considerations​

To use the Czech Bank iD buttons, texts, logos and other graphic elements correctly in your applications, you need to follow the UX style guide at https://ux.bankid.cz/.

Next steps​

Continue your journey with more Czech Bank iD guides:

Attributes reference
Attributes reference and data for Czech Bank iD

Dive deeper into the Signicat Authentication REST API:

Authentication REST API documentation
Find out more about the Signicat Authentication REST API.
Authentication REST API reference
Discover the endpoints of the Authentication REST API
On this page