Skip to main content

Integration with Authentication REST API

This page details how to set up an integration with Email OTP using the Signicat Authentication REST API with redirect flow.

The Signicat Authentication REST API relies on the OAuth 2.0 protocol for authorisation. Requests are sent from your backend server to Signicat's Authentication REST API.

If you want to find out more about the Signicat Authentication REST API, see:

Before you begin​

Before starting your OIDC integration with Email OTP, make sure you have configured your Signicat account.

API configuration​

To connect to Signicat APIs, you need an API client which consists of a client_id/client_secret pair associated with either your organisation or one of your accounts.

In a typical flow, you pass the client credentials in the API request to obtain an access token. Then, you include the access token as an HTTP Bearer authentication header when sending requests to the Signicat Authentication REST API.

API client credentials​

You can obtain your API client credentials in the Signicat Dashboard. Learn how to do this in the Accessing Signicat API products section.

To connect to the Authentication REST API, make sure you use the following settings:

  • signicat-api in the Allowed scopes.
  • Authentication REST API in the Permissions tab of your API client.
  • A client secret is associated to the API client.

Obtain an access token​

Before you continue with the steps in this guide, make sure you obtain an access token as explained in the Obtaining an access token section.

Redirect flow​

This section details how to set up authentication for Email OTP using the redirect flow. The redirect flow allows you to pass an authorization URL to your end-users which they will open in a browser.

1. Create a session​

Request​

To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions.

For example, include the following fields in the payload:

{
    "allowedProviders": ["otp-email"],
    "flow": "redirect",
    "requestedAttributes": [
        "idpId",
        "email"
    ],
    "language": "en",
    "callbackUrls": {
        "success": "https://example.test/success",
        "abort": "https://example.test/abort",
        "error": "https://example.test/error"
    }
}

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

Note the following fields in the payload of the request:

You can find an overview of attributes and responses in the Attributes mapping for the Authentication REST API.

Response​

Here is an example response after you have created a session:

{
    "id": "58126fb8-c5e2-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.test/success?sessionId=58126fb8-c5e2...",
        "abort": "https://example.test/abort?sessionId=58126fb8-c5e2...",
        "error": "https://example.test/error?sessionId=58126fb8-c5e2..."
    },
    "allowedProviders": [
        "otp-email"
    ],
    "flow": "redirect",
    "language": "en",
    "requestedAttributes": [
        "idpId",
        "email"
    ],
    "sessionLifetime": 600
}

Use the response​

You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the end-user to perform the Email OTP authentication in context of the session you just created.

User journey​

When end-users access the authentication URL, the user journey looks like this:

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

2. Get the session status​

Request​

To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can find the id value in the response that was returned when you created the session. No data specific for Email OTP needs to be included in this request.

For more information about the "Get session status" endpoint, see the API Reference description.

Response​

The response contains a status field that informs you about the current status of the session. For example, the response for a successfully completed session is:

{
    "id": "58126fb8-c5e2-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "SUCCESS",
    "provider": "otp-email",
    "language": "en",
    ...
}
Status overview​

Use the response​

If the returned status is SUCCESS, the subject object contains information about the authenticated user.

{
    "id": "XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX",
    "accountId": "<ACCOUNT_ID>",
    "authenticationUrl": "https://example.sandbox.signicat.com/broker/sp/external-service/login?messageId=XXXXXXXX-fb55-bd4e-8dbc-XXXXXXXX&transactionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX",
    "status": "SUCCESS",
    "provider": "otp-email",
    "subject": {
        "id": "TOuh-Q-Qx2-XXXXXXXX",
        "idpId": "signikitten@example.com",
        "email": "signikitten@example.com"
    },
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX",
        "abort": "https://example.com/abort?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX",
        "error": "https://example.com/error?sessionId=XXXXXXXX-f8d9-b145-a5f0-XXXXXXXX"
    },
    "environment": {
        "ipAddress": "192.0.2.2",
        "userAgent": ""
    },
    "allowedProviders": [
        "otp-email"
    ],
    "flow": "redirect",
    "language": "en",
    "requestedAttributes": [
        "idpId",
        "email"
    ],
    "sessionLifetime": 600
}

In the object you can also see the service provider specified in the provider field. This can be useful if you specified more than one provider when you created the session.

Set the UI language​

To change the language on the Email OTP UI, use the language parameter in the payload of your request to the CreateSession endpoint. For example, use "language": "el" to set the Email OTP UI to Greek.

Default language

By default, the UI language is English.

For an overview of the languages supported, see the Attributes reference.

Prefill user information​

When using the Signicat REST API, you pass user data in the prefilledInput field in the payload of the request to the CreateSession endpoint, so that the end-user does not have to enter their email manually when authenticating. For example, this applies to cases when you already know the email address.

To specify an email address in the authentication URL, the payload of the request might looks like this:

...
"prefilledInput": {
	"email": "email@example.com",
},
...

This will display the email address to the end-user when they start the authentication flow. To learn more about data prefilling, see the Prefilling user information conceptual guide.

Verify the email address

For security reasons, we recommend you verify that the email address you receive in the response from Email OTP matches the email address you prefilled in the authentication URL.

Attributes​

For an overview of the API attributes for Email OTP, see the Attributes reference.

Next steps​

Learn more about Signicat Authentication REST API flows and endpoints in the Authentication REST API documentation

Last updated:
On this page