# Authentication REST API

Page contents

Available flows
- Redirect flow
- Headless flow
Encrypted responses from Signicat
IdP discovery
- ID method discovery
- Provider discovery
Migrating from Express
API reference

The Signicat Authentication REST API enables you to authenticate your end-users in an easy and secure way. With the Authentication REST API, you can offer a variety of authentication flows from your backend systems. Using such a REST API, can often result in a less complex integration compared to OIDC or SAML 2.0.

The main advantages of using this API compared to OIDC or SAML 2.0 are:

You do not need to implement complex protocols, since this is just a very simple REST API.
You can support complex flows such as headless flow.

The biggest disadvantages are:

You always need a backend system to do the API calls securely.
You may have to write more custom code compared to using a pre-made library or SDK for OIDC or SAML.

# Available flows

The Authentication REST API currently supports the redirect and headless flow (see below). We plan to implement more flows in the future.

# Redirect flow

The redirect flow allows you to pass a URL to your end-users which they will open in a browser. It is called a redirect flow since your end-users are redirected several times during the authentication session. At the end of this redirect chain, they will arrive at what you have defined as the "success callbackUrl" for that specific session. This should be an endpoint at your backend system. Your backend will then get the authentication session from our endpoint, which includes the information about the authenticated person (subject).

Sequence diagram example click-to-zoom

# Headless flow

The headless flow allows you to provide your own user interface within your app or website. Requests are sent from your backend server to Signicat's Authentication REST API.

Headless flow is currently only available for Swedish BankID. For more information about how to set up this up, see Headless flow.

# Encrypted responses from Signicat

Signicat can send encrypted responses. This means we will encrypt the responses on the given session.

All responses from Signicat are fully encrypted on the transport layer with HTTPS. You can implement message-level encryption as an additional security layer.

This section explains how to set up and process encrypted responses.

Important

For FTN, you are required to receive encrypted responses. If you do not set this up correctly, FTN will fail and you will not be able to obtain any FTN authentication results.

# Prerequisites

To use encrypted responses, you must first generate a key pair.

Note

You can use our website JWK generator by Signicat (opens new window) to securely generate this key pair, or any other method that is convenient for you; for example, OpenSSL, or a JOSE or JWK library for the language of your choice.

The key pair needs to be in a valid JWK format.
The technical requirements for the keys are:

# For RSA key types

Field name	Value
Algorithm (`alg`)	`RSA-OAEP`
Key type (`kty`)	`RSA`

For RSA, we support key sizes of 2048 bits and 4096 bits if required.

# For elliptic curve key types

Note

Support for Elliptic curve cryptography (ECC) key pairs will be available soon.

Field name	Value
Algorithm (`alg`)	`ECDH-ES`
Curve (`crv`)	`P-256`, `P-348`, `P-521`
Key type (`kty`)	`EC`

# Implementation

To implement encrypted responses, you need to include the additional field encryptionPublicKey when making a request to the Create session (opens new window) endpoint. You can find more details about this field in our API specifications.

Following this, all of your responses for both the Create session (opens new window) and the Get session (opens new window) endpoints will be encrypted with this key. The responses will also be encrypted in our session storage. This ensures full encryption in the Authentication REST API.

# Example request

{
	"allowedProviders": [
		"nbid"
	],
	"flow": "redirect",
	"requestedAttributes": [
		"firstName",
		"lastName",
		"dateOfBirth",
		"nin"
	],
	"callbackUrls": {
		"success": "https://postman-echo.com/get?status=success",
		"abort": "https://postman-echo.com/get?status=abort",
		"error": "https://postman-echo.com/get?status=error"
	},
	"encryptionPublicKey": {
		"alg": "RSA-OAEP",
		"e": "AQAB",
		"kty": "RSA",
		"n": "1soz_f_GSGVYfYwIRSu6mkIsyymeqjEXdO-24ffhZnrwKNEeqO9vwxVKHpAUMA55QGBhPl-epJjYjzy_24n-0qvJEwddLvo0cuO0N-ms0LhB8WlUwhLKp6pqj_AO46Pt7qyBNFlWQh3KF_UakAb1Jq1P97Ba0FAIXJBaTKvnZ5hxwJY5i2tPA_NNQT5D40nqc0BNWS0Iv6Ww9oYfQn3pecyOygTFGMTg2SQ3t-4XRGaKclOwExIWTJTv21slOBMJQLomO0hJtnRAB9aBZRgit8K41TzuBp_wpbFlYLoep8lRyG-n2A_1yHlww1P2pVzmlynNDO87ERek6EyI6uPZvQ",
		"use": "enc"
	}
}

# Example response

HTTP/2 200 
Content-Length: 2048
Content-Type: application/jose
Date: Tue, 07 Feb 2023 15:08:43 GMT
eyJh...QifQ.Qq5TQR...xN-PQ.ojSGehTV7xw_xE078sFnTg.in8a...SITqA.SyVNrXe0C3UkKBQ_AVyQiw

The response will now say Content-Type: application/jose instead of the usual Content-Type: application/json. This tells you that the response is a JWE (JWT) as per RFC 7516: JSON Web Encryption (JWE) (opens new window).

You can now use your private key from the key pair you created earlier to decrypt this message. The payload of the JWE is a JSON structure that is exactly the same as a non-encrypted reply, so you will be able to continue with your normal implementation once you have decrypted the payload.

# Example code

Important

This code example is for illustrative purposes only. It is not intended for use in production. Signicat will not be held responsible if this code example is used inappropriately.

from jwcrypto import jwk, jwe

# ATTENTION: Insert your nested JWT (that you received from the Signicat Authentication REST API) here.
jwe_serialized = "eyJh...QifQ.Qq5TQR...xN-PQ.ojSGehTV7xw_xE078sFnTg.in8a...SITqA.SyVNrXe0C3UkKBQ_AVyQiw"

# For the sake of simplicity in this example, the JWKs have been manually loaded into a dictionary.
# In practice, you should do this in a secure manner. The jwe_private_key should be stored securely on your premises.

jwe_private_key = {
    "alg": "RSA-OAEP",
    "d": "IchOWqQUx_S2sRJqB5Ub5aDEYlTiuXJ8tb3xRgPCjieGZ-kSOTBlo-mQjZOMNU3FeOBf0xtffJR0tTyxEWLYM0LlHorRN28PekWBpiyo63AboRB3zgl-GdZmKcrwUJILPXeg376wYDhGvbNlkOMjQkjOk87HTc3Urthed4IvJH4N7SpHBuzFHucb_1Zcq7i_UZrvQecNZoODoeTJIeaN4LoN4AB63Jc75doVBvTqyyKl39VdrdDzsv17WOq_HjFe0KLwFGjK6VEQbiaNMS7Jh6XoKVkiVLKT2uzyzpWCHu68gB6BDuItlllhbMYYCW9yoC7mFkWroG_EZj8PJL-58Q",
    "dp": "UU2ygH3JEjmyTEiOmNHSpoDjnn5JR0nmZDZ4AOrEUMuMmXbnkNfXN5vGmo8hBZbWUBcXN5CkeGysiFByldfw1oVRlNoA1np00Gtb_8RsaElcIr1aWSgACArCsbhplDNSzNDPjm6FvW21Rkdm0AwVmak7YgtMgodq1TLBUwd_-uE",
    "dq": "VqinrWjEIgryjHdQmb_cFhxGFN167EvM5PSjrj3w1Dg6453MKZjriJmIT8LZbbcrLalkaeje2PK0Koy1ZEyBvmRHlZDShX8AigXeY2s478wWVk03bsJyWcrMO2Lokal_Zn6_ULJYkmIHPoXzzB56odEqxgQnP1ZM0O0nS2J76k0",
    "e": "AQAB",
    "kty": "RSA",
    "n": "1soz_f_GSGVYfYwIRSu6mkIsyymeqjEXdO-24ffhZnrwKNEeqO9vwxVKHpAUMA55QGBhPl-epJjYjzy_24n-0qvJEwddLvo0cuO0N-ms0LhB8WlUwhLKp6pqj_AO46Pt7qyBNFlWQh3KF_UakAb1Jq1P97Ba0FAIXJBaTKvnZ5hxwJY5i2tPA_NNQT5D40nqc0BNWS0Iv6Ww9oYfQn3pecyOygTFGMTg2SQ3t-4XRGaKclOwExIWTJTv21slOBMJQLomO0hJtnRAB9aBZRgit8K41TzuBp_wpbFlYLoep8lRyG-n2A_1yHlww1P2pVzmlynNDO87ERek6EyI6uPZvQ",
    "p": "2m4looTgE4Gx8Uu8mTjv3PGlHLYuG5zTIJAG9joxnOO-JdvIwUIi4Kc4QN-cJJpZsdpBQs5HKcI4F6TFccO_lx7q4xgXgzGBTMy6lLsYgFgIBM0SWXqQ3Ws35ewt40v9Zhs0kaRSpzuS0Pik90cwsPcMexB2BJ3kTSEgMctEDLE",
    "q": "-7vDS1Cu9RuXX7Xktg6Ftn-FGiCQQ26is7s-ixwv0XGhV2nxzzKKhNcattYWFnOAA91NOzBy8XWaDMli2vNqqSlcDnvAZGpppv-nJRD3wyVvcYWV3Bi_xGsjh5NiyEC8RQOj5rzZ9jP3EJdw3pvfAZj_ncSfwpuGH9ESPaJssM0",
    "qi": "coF8GU0fQ9-KcZfz2Vp8Si4MwzQElFwaAkJX64cZe57-IjDYWlU66VMB1tsoJbCWt_vWOSmOCXROVOSYIdI85y_W2PtSjRGxKInMlQ7MGpqhAVv75nD_k0yf2y8AFZk4SCoiVFlQWJ44Ke8vaf7FTKBCgzbznkY2xvBqYRv7N8Y",
    "use": "enc"
}
# Loading JWK key
jwk_jwe_private_key = jwk.JWK()
jwk_jwe_private_key.import_key(**jwe_private_key)

jwetoken = jwe.JWE()
jwetoken.deserialize(jwe_serialized)
jwetoken.decrypt(jwk_jwe_private_key)
payload = jwetoken.payload.decode('unicode_escape')
print(payload)

# IdP discovery

If you have more than one ID method configured in your Signicat account, you can use IdP discovery to route the end-user to a specific ID method for authentication, therefore skipping the ID method selection screen where typically the end-user can choose their preferred ID method (from all the methods active in your account). This feature is also known as IdP scoping or IdP routing rules.

With IdP discovery, you can define logic to determine two aspects of an authentication flow:

ID method discovery: You can define which ID method to use, such as iDIN or Norwegian BankID.
Provider discovery: You can specify the entity or provider (such as a bank) for an ID method. For example, for iDIN you can choose to route end-user only to one of the banks. Note that this functionality is limited to certain ID methods only.

# ID method discovery

To control which ID method to display to your end-users, you can use the allowedProviders field in the payload of the CreateSession request to the Signicat Authentication REST API.

You can find an overview of the values for each ID method at https://<YOUR_ACCOUNT_DOMAIN>/broker/idps. Use the value of internalName.

# Skip IdP selection screen

If you define only one ID method in the payload, the end-user is routed to the IdP-specific authentication page, thus automatically skipping the IdP selection screen during authentication.

For example, to direct the end-user to SMS OTP, thus skipping the ID methods selection screen, pass the following payload in your request:

...
"allowedProviders": [
	"sms-otp",
	],
...

This prevents end-users from choosing other ID methods that may be active in your account.

# How to display a subset of ID methods

To let the end-user choose among a subset of ID methods active in your account, specify multiple values in the allowedProviders key. For example, to display Email OTP and FTN to the end-user in the ID method selection screen, use:

...
"allowedProviders": [
	"email-otp",
	"ftn",
	],
...

When the authentication flow starts, the end-user sees a selection screen where they can choose between Email OTP and FTN.

# Provider discovery

In some cases, ID methods are comprised of a network of identity providers (or issuers), such as banks, that collectively offer authentication to their customers. You may want to offer your end-users only a limited number of these providers when the end-users authenticate with an ID method.

To control the providers you make available for each authentication session, use the additionalParameters field in the payload of the CreateSession request to the Signicat Authentication REST API.

Below, you can find an overview of the attributes available for each ID method:

ID method	Attribute	Providers
iDIN	`idin_idp`	View the list of iDIN issuers (banks) active in your account at `https://<YOUR_ACCOUNT_DOMAIN>.com/broker/authn/idin/issuers`, where `<YOUR_ACCOUNT_DOMAIN>` is the domain you registered in the Signicat Dashboard Domain management (opens new window).
FTN	`ftn_idp`	View the list of FTN issuers in the ID method documentation for FTN.

For example, when authenticating end-users with the Finnish Trust Network (FTN), you can choose which banks to include in the authentication process. To restrict the banks available to end-users to use the following fields in the payload:

...
"additionalParameters": {
	"ftn_idp": [
		"fi-aktia",
		"fi-danskebank",
	],
},
...

You can find more details for each ID method in the respective ID method documentation.

# Migrating from Express

For the Signicat Digital Trust Platform (DTP), we have made the Signicat Authentication REST API more tightly integrated with the platform to take full advantage of its possibilities. However, we have taken care to make the migration from the old API in Express as seamless as possible.

# Key differences

Authorization: DTP does not use the same access and identity and access management (IAM) control as Express.
Endpoints: The general flow is the same, but with minor differences.
Data models: The request and response objects have slightly different structures.
Encrypted responses: DTP does not sign encrypted responses.

In addition, there are some general differences between Express and DTP; the concept of organisations and accounts, eIDs, platform differences, etc. You can find more information about these concepts in the General information section.

# Authorization

Signicat DTP features a richer and more powerful access and IAM control. Although technically different, it is practically similar as it is still using an OAuth2 client credentials flow.

The executive summary is that you will use a new token URL, a new client (client ID and client secret) and a different scope.

For more information on how to authorise, see Accessing Signicat API products.

# Endpoints

We have made some minor changes to our endpoints, but the general structure remains much the same.

Name	Endpoint	Change
Create session	`POST /sessions`	New parameter, `signicat-accountId`.
Retrieve session	`GET /sessions/{id}`	New parameter, `signicat-accountId`.
List sessions	`GET /sessions/{id}`	This endpoint has been deprecated.
Invalidate session	`GET /sessions/{id}`	This endpoint has been deprecated.

Deprecated endpoints

"List sessions" and "Invalidate session" have been deprecated because of a different way of treating non-permanent data in DTP. When a session expires in DTP (with sessionLifetime), it's completely deleted from our system. It's done this way to increase protection of PII and simplify data management.

# Data models

We have improved the structure of the request and response objects to make them clearer and more concise.

# Request

Old name (Express)	New name (DTP)	Comment
`allowedProviders`	`allowedProviders`	Same field name, but new values: `["nbid", "sbid"]`.
`include`	`requestedAttributes`	New field name and new values (see API specification for details).
`redirectSettings`	`CallbackUrls`	New field name and new values: `["success", "abort", "error"]`.
-	`sessionLifetime`	New field (not required).
-	`themeId`	New field (not required).

# Response

Old Name (Express)	New Name (DTP)	Comment
`url`	`authenticationUrl`	New field name, but the same purpose.
`status`	`status`	Same field name, but values are capitalized.
`identity`	`subject`	New field name and new values: (see API specification for details).
`identity.providerId`	`subject.idpId`	New field name, but the same purpose. Field representing the user's unique ID from the eID provider.

# Encrypted responses

Although it is possible to encrypt the response you receive from Signicat, DTP does not sign the response (with a digital signature). This means that you only need to decrypt the response, as explained in Encrypted responses from Signicat.

# API reference

In our Authentication REST API reference, you can find information about the available endpoints and properties, as well as sample requests and responses.

Authentication REST API

Configure your Authentication REST API

REST

← Level of Assurance contracts Error codes →