For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Authentication REST API

This guide shows you how to authenticate end-users with the EUDI Wallet using the Signicat Authentication REST API with a redirect flow.

Prerequisites​

Before starting your integration, ensure to complete the following steps:

  1. Complete the setup in the Configure identity wallets guide.

  2. For the complete documentation index, see llms.txt

    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 you how to set up authentication using the cross-device redirect flow. This flow allows you to pass an authorisation URL that your end-users open in a desktop or PC browser. Then, the users need to verify themselves using their wallet app on a mobile device before returning to the desktop or PC browser. The term cross-device redirect flow indicates this switch between separate physical devices.

Supported flows

Same-device redirect flow (where the entire authentication occurs on the user's mobile phone) is not supported yet. Instead, users must initiate the authentication flow on a desktop or PC browser and complete it on their mobile phone.

Implementation guide​

A successful implementation involves the following steps:

  1. Create a session
  2. End-user authentication
  3. Get the session status

1. Create a session​

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

Request​

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

This is an example of what your request could look like:

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

{
    "allowedProviders": [
        "wallet-verifier"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "firstName",
        "lastName",
        "dateOfBirth",
        "gender",
        "nin",
        "address",
        "nationality",
        "email",
        "walletVerifierDateOfExpiry",
        "walletVerifierDateOfIssuance",
        "walletVerifierPersonalAdministrativeNumber",
        "walletVerifierIssuingAuthority",
        "walletVerifierIssuingCountry",
        "walletVerifierDocumentNumber",
        "walletVerifierIssuingJurisdiction",
        "walletVerifierTrustAnchor",
        "walletVerifierAttestationLegalCategory",
        "walletVerifierPlaceOfBirthLocality",
        "walletVerifierPlaceOfBirthRegion",
        "walletVerifierPlaceOfBirthCountry"
    ],
    "callbackUrls": {
        "success": "https://example.com/get?status=success",
        "abort": "https://example.com/get?status=abort",
        "error": "https://example.com/get?status=error"
    }
}

Note the following fields in the request payload:

Personal identity data (PID) and other attributes

To view a complete list of supported user claims, including personal identity data (PID) and wallet device metadata, see the Attributes reference.

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

Response​

After you create a session, you receive a response that contains:

  • A summary of your request
  • A unique ID for the process
  • The link for the authenticationUrl

Here is an example response:

{
  "id": "efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
  "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
  "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=3b03d4b1-da85-8f42-85f5-e14a826a4496&transactionId=4fce3e52-e779-a645-ac40-d70a39913b7c",
  "status": "CREATED",
  "callbackUrls": {
    "success": "https://example.com:443/get?status=success&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
    "abort": "https://example.com:443/get?status=abort&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
    "error": "https://example.com:443/get?status=error&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28"
  },
  "allowedProviders": [
    "wallet-verifier"
  ],
  "language": "en",
  "flow": "redirect",
  "requestedAttributes": [
      "firstName",
      "lastName",
      "dateOfBirth",
      "gender",
      "nin",
      "address",
      "nationality",
      "email",
      "walletVerifierDateOfExpiry",
      "walletVerifierDateOfIssuance",
      "walletVerifierPersonalAdministrativeNumber",
      "walletVerifierIssuingAuthority",
      "walletVerifierIssuingCountry",
      "walletVerifierDocumentNumber",
      "walletVerifierIssuingJurisdiction",
      "walletVerifierTrustAnchor",
      "walletVerifierAttestationLegalCategory",
      "walletVerifierPlaceOfBirthLocality",
      "walletVerifierPlaceOfBirthRegion",
      "walletVerifierPlaceOfBirthCountry"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-08-14T12:43:22.0805822+00:00"
}

Now, your application needs to redirect the end-user to the authenticationUrl you obtained in the response.

2. End-user authentication​

The authenticationUrl is a unique URL that allows the end-user to perform authentication in the context of the session you just created. Your application needs to route the end-user to the authenticationUrl you obtained in the response. The authenticationUrl is where the QR code for authentication is displayed to your end-users.

User journey​

To authenticate with their EUDI Wallet, users will complete a cross-device flow that involves these operations:

  1. QR code scan: Your service routes the user to the authenticationUrl on their desktop/PC browser. This is where the Signicat eID and Wallet Hub displays a QR code. The user opens the EUDI Wallet app on their smartphone and scans the QR code.
  2. Consent and verification: After scanning, the user's mobile app displays the specific personal data requested, such as Person Identification Data (PID). The user reviews this request and confirms by entering their PIN or verifying with biometrics.
  3. Redirect: After successful verification, the desktop/PC browser automatically resumes and redirects the user back to the appropriate callback URL (for example, the success URL) with the sessionId.

Test an authentication​

To test an authentication flow during the implementation phase, you can use the test user you generated in your wallet app, as explained in the Try it out page.

3. Get the session status​

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

Request​

To get the status of a session, 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 request example above, substitute {SESSION_ID} with the value of the session id you received in the response after creating the session. For example, if the id was c99e17e2-b124-f549-a88c-408f8e555d31, your request would be directed to https://api.signicat.com/auth/rest/sessions/c99e17e2-b124-f549-a88c-408f8e555d31.

Response​

The response contains a status field with 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​

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

For example, a typical response from authentication looks like this:

{
    "id": "efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=3b03d4b1-da85-8f42-85f5-e14a826a4496&transactionId=4fce3e52-e779-a645-ac40-d70a39913b7c",
    "status": "SUCCESS",
    "provider": "wallet-verifier",
    "subject": {
        "id": "-KawNflomN6v649lT3Y-cwdJvmweDbsp-NyT9xflM8U=",
        "firstName": "Anna",
        "lastName": "Johansson",
        "dateOfBirth": "1990-07-22",
        "email": "anna.johansson@example.com",
        "address": "Kungsportsavenyen 25, 411 36 Gothenburg, Sweden",
        "addressFormatted": {
            "FullAddress": "Kungsportsavenyen 25, 411 36 Gothenburg, Sweden",
            "Street": "Kungsportsavenyen",
            "HouseNumber": "25",
            "City": "Gothenburg",
            "Region": "Vastra Gotaland",
            "PostalCode": "411 36",
            "Country": "SE"
        },
        "gender": "2",
        "nationality": "SE,NO"
    },
    "callbackUrls": {
        "success": "https://example.com:443/get?status=success&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
        "abort": "https://example.com:443/get?status=abort&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28",
        "error": "https://example.com:443/get?status=error&sessionId=efacd04b-9e84-4328-b8ae-a4cc59bb4b28"
    },
    "environment": {
          "ipAddress": "192.0.2.0",
          "userAgent": "userAgent"
    },
    "loa": "unspecified",
    "allowedProviders": [
        "wallet-verifier"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "firstName",
        "lastName",
        "dateOfBirth",
        "gender",
        "nin",
        "address",
        "nationality",
        "email",
        "walletVerifierDateOfExpiry",
        "walletVerifierDateOfIssuance",
        "walletVerifierPersonalAdministrativeNumber",
        "walletVerifierIssuingAuthority",
        "walletVerifierIssuingCountry",
        "walletVerifierDocumentNumber",
        "walletVerifierIssuingJurisdiction",
        "walletVerifierTrustAnchor",
        "walletVerifierAttestationLegalCategory",
        "walletVerifierPlaceOfBirthLocality",
        "walletVerifierPlaceOfBirthRegion",
        "walletVerifierPlaceOfBirthCountry"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-08-12T14:37:20.1905445+00:00"
}

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

Success!

You have now completed an authentication flow with the EUDI Wallet using the Signicat Authentication REST API.

Next steps and security considerations​

After you retrieve the identity data of a user, you must integrate this information into your application's user lifecycle and secure the active session. This typically involves matching the returned attributes to a user record in your database or initiating your internal registration flow. To complete the transaction securely, ensure your backend validates the integrity of the session state before granting the user access to your services.

Learn more​

Continue your journey with more EUDI Wallet guides:

Attributes reference
Attributes and claims for the EUDI Wallet

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