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

Redirect flow

In a redirect flow, your application redirects the end-user from your website or app to a Signicat-hosted authentication page in a web browser. The end-user completes authentication with their chosen electronic identity (eID) or digital wallet, and Signicat redirects them back to your application with the result.

General implementation guide

You can use this guide as a foundation to understand how a redirect authentication flow works with our Authentication REST API.

Note that it is important that you check the individual eIDs documentation to learn about the unique features and specific parameters supported by the eID provider of your choice.

Flow overview​

The redirect flow consists of five main steps:

  1. Create an authentication session: Your backend sends a request to the Authentication REST API specifying callback URLs and optional provider requirements.
  2. Redirect the end-user: Your application redirects the end-user's browser to the returned authenticationUrl.
  3. Authenticate the end-user: The end-user identifies themselves through the hosted interface and their identity provider.
  4. Handle the callback: Signicat redirects the end-user back to your pre-configured callback URL.
  5. Retrieve session details: Your backend queries the session to obtain verified identity attributes and status.
Redirect flow sequence diagram

Sequence diagram showing the redirect flow for Signicat Authentication REST API

Prerequisites​

Before you implement the redirect flow, complete the following prerequisites:

  1. Add and configure at least one eID provider in the Signicat Dashboard under Products > eID and Wallet Hub > eIDs. Learn more in the Add eIDs 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

Step 1: Create an authentication session​

To start the authentication process, you need to create a session using the Authentication REST API. To do this, send a POST request from your backend server to https://api.signicat.com/auth/rest/sessions ensuring to specify redirect as the flow type.

Request​

POST https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId} HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "flow": "redirect",
  "callbackUrls": {
    "success": "https://example.com/auth/callback/success",
    "abort": "https://example.com/auth/callback/abort",
    "error": "https://example.com/auth/callback/error"
  },
  "allowedProviders": [
    "<EID_PROVIDER>"
  ],
  "requestedAttributes": [
    "firstName",
    "lastName",
    "nin",
    "dateOfBirth"
  ]
}

To learn more about the properties of the request payload, see the Create a session endpoint description.

Key parameters​

  • flow: Specifies the flow type. You must set this to redirect.
  • callbackUrls: The absolute URLs where Signicat routes the end-user after authentication:
    • success: The URL used when the end-user authenticates successfully.
    • abort: The URL used if the end-user cancels the authentication process.
    • error: The URL used if an unrecoverable error occurs during authentication.
  • allowedProviders: Optional. A list of specific eID provider identifiers. If left blank, all configured eIDs on your account are displayed to the end-user in a selection screen.
  • requestedAttributes: A list of identity attributes you want Signicat to retrieve from the eID provider. Attribute codes and data availability varies depending on the eID provider(s) you provide in allowedProviders.
Provider-specific parameters

Request parameters and supported attributes vary depending on the eID provider you use in your application. To find out which parameters and configuration options apply to an eID, see the individual eIDs documentation.

Response​

After you create a session, you receive a response containing the following fields:

  • Metadata about your request
  • id: The unique identifier for the session
  • authenticationUrl: The authentication URL where to direct the end-user

Response example

{
    "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
    "status": "CREATED",
    "flow": "redirect",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31",
    "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": [
       "<EID_PROVIDER>"
    ],
    "requestedAttributes": [
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-10-11T07:56:36.587157+00:00"
}

The CREATED status means the end-user has not started to authenticate yet.

Step 2: Redirect the end-user​

Redirect the end-user's browser to the authenticationUrl received in the session creation response.

https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31

Step 3: End-user authenticates​

The end-user completes the following steps to authenticate:

  1. If multiple eID providers are enabled, the end-user selects their preferred method. This is a Signicat-hosted selection screen.
  2. The end-user follows the authentication steps for their chosen eID (such as entering credentials, scanning a QR code or confirming in a mobile app). This is the eID provider's screen.

Get the session status​

During an active authentication session, you can monitor the status to gauge the progress of the authentication, such as whether the flow has started, failed or completed. Note that responses from successful authentications contain the end-user personal data.

Request​

To retrieve the status of an ongoing session, you need to send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can obtain the id value from the response you received upon creating the session.

In the response example above, the id is c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 so the request would be

GET https://api.signicat.com/auth/rest/sessions/c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

For more information about the request, see the Get session status endpoint description.

Status overview​

The status field could contain one of the following values:

Step 4: Handle the callback​

When the authentication finishes, Signicat redirects the end-user to the corresponding URL you provided in callbackUrls.

Signicat appends the sessionId query parameter to the callback URL:

GET https://example.com/auth/callback/success?sessionId=c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 HTTP/1.1
Security considerations

The callback is not a recommended way to grant user access or verify claims, as URL query parameters can be intercepted or manipulated. Always validate the end-user's identity from your backend using the response from the session details.

Step 5: Retrieve session details​

When your backend receives the callback or detects that the session is complete, send a GET request to /auth/rest/sessions/{id} using the stored session ID.

Request​

GET https://api.signicat.com/auth/rest/sessions/c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

Response​

If the authentication succeeded, the session returns a SUCCESS status and includes the retrieved subject and identity attributes:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "<YOUR_ACCOUNT_ID>",
  "status": "SUCCESS",
  "provider": "<EID_PROVIDER>",
  "subject": {
    "id": "9578-6000-4-48855",
    "idpId": "9578-6000-4-48855",
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "2002-06-01",
    "nin": {
        "value": "string",
        "issuingCountry": "string",
        "type": "string"
    }
  },
  "environment": {
    "ipAddress": "127.0.0.1",
    "userAgent": "user_agent_test"
  },
  "flow": "redirect",
}

Upon receiving a SUCCESS status, you should process and validate the end-user's data according to your use case to log the end-user into your application.

Success!

You have now completed a redirect flow using the Signicat Authentication REST API.

Next steps​

Explore more topics to build your integration with the eID and Wallet Hub:

eIDs
Find out more about the eIDs
Concepts
Learn about eID and Wallet Hub concepts
Authentication REST API reference
Discover the endpoints of the Authentication REST API
On this page