Authentication REST API
This page details how to set up authentication for MitID using the redirect flow. The redirect flow allows you to pass a URL to your end-users which they will open in a browser.
Set up the API client
1. Get client credentials
Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. How to do this is described in Accessing Signicat API products > Set up an API client.
2. Obtain access token
You use the client credentials in a request to obtain an access token. The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests. For more details, see Accessing Signicat API products > Obtaining an access token.
Implement the authentication flow
1. Build the authentication request (CreateSession)
This section describes how to send a request to the CreateSession endpoint, to create a session and start an authentication.
To begin the authentication flow, your application must first start a session by utilising the CreateSession endpoint. The endpoint will automatically create a session when you send a request. The flow and resulting information from the transaction depends on the parameters you pass in the body. The response from this endpoint will contain an authentication URL, to which you can redirect the end-user to start their transaction.
To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId}.
You can find your accountId in the Signicat Dashboard.
The following sub-sections show examples and descriptions of attributes that you can include in the request.
Request example
Here is an example request body for a "basic" MitID authentication:
{
"flow": "redirect",
"allowedProviders": [
"mitid"
],
"prefilledInput": {
"mitidAppType": "android",
},
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"mitidHasCpr",
"mitidReferenceTextBody",
"mitidCprSource",
"mitidNameAndAddressProtection",
"mitidIal",
"mitidLoa",
"mitidAal",
"mitidFal",
"mitidUuid"
],
"callbackUrls": {
"success": "https://signicat.com",
"abort": "https://example.test/abort",
"error": "https://example.test/error"
}
}
Upon sending this request, a session will be created with MitID.
If the authentication completes successfully, the final result will contain the attributes that were requested.
Attribute descriptions
To initialise an authentication with MitID, you can use the following attributes in the initial request:
For more detailed field descriptions, see the API reference.
Control the user flow (additionalParameters)
You use additionalParameters to control the redirect flow. This is not a required field.
User attributes (requestedAttributes)
You can request the following attributes from users of MitID.
You add them in the requestedAttributes as shown in the request example above.
Response example (CreateSession)
Here is an example response after you have created a session:
{
"id": "1cac32ef-38a...",
"accountId": "a-sdge-...",
"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=9102c493-b816-ea4f-b120-cdd95f982bf6&transactionId=1cac32ef-38a7-9249-969b-61af48bc49c2",
"status": "CREATED",
"callbackUrls": {
"success": "https://example.com/success??sessionId=1cac32ef-38a7-...",
"abort": "https://example.com/abort?sessionId=1cac32ef-38a7-...",
"error": "https://example.com/error?sessionId=1cac32ef-38a7-..."
},
"allowedProviders": [
"mitid"
],
"flow": "redirect",
"prefilledInput": {
"mitidAppType": "android"
},
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"mitidHasCpr",
"mitidReferenceTextBody",
"mitidCprSource",
"mitidNameAndAddressProtection",
"mitidIal",
"mitidLoa",
"mitidAal",
"mitidFal",
"mitidUuid"
],
"sessionLifetime": 1200,
"expiresAt": "2024-11-15T15:08:25.7016512+00:00"
}
What you need to do with the response
You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the user to perform the MitID authentication in context of the session you just created.
"https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=9102c493-b816-ea4f-b120-cdd95f982bf6&transactionId=1cac32ef-38a7-9249-969b-61af48bc49c2"
End-user authentication
The end-user follows these steps:
- On your website/application, the end-user clicks on a button to authenticate with MitID. Your application sends a request to start an authentication with MitID, as described in the previous section.
- The end-user is redirected to the MitID login page.
- The end-user logs in using their MitID credentials (this step may involve two-factor authentication).
After the end-user approves the request, the browser is redirected back to the relevant callbackUrls specified in the CreateSession request.
2. Obtain user information (GetSession)
You use the GetSession endpoint to poll for information regarding the session and ongoing authentication.
Once the authentication is successful, the response will contain the user information requested in the CreateSession call that was done earlier.
Request
No data specific for MitID needs to be provided in this 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.
Response
The response contains a status field, which indicates the current status of the session. Below you can see an example response for a successfully completed session:
{
"id": "a993cc3a-cad8-...",
"accountId": "a-sdge-...",
"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=27c019f1-de66-5840-a220-5f66e673c65e&transactionId=a993cc3a-cad8-f041-ae83-351a55ca5202",
"status": "SUCCESS",
"provider": "mitid",
"subject": {
"id": "MbLYMQJMSQAwk-...",
"name": "Valona Jensen",
"firstName": "Valona",
"lastName": "Jensen",
"dateOfBirth": "1990-02-17",
"mitidFal": "HIGH",
"mitidHasCpr": "true",
"mitidAal": "SUBSTANTIAL",
"mitidUuid": "8cb1e51c-13aa-4044-b9ac-8978cf1f113c",
"mitidIal": "SUBSTANTIAL",
"mitidReferenceTextBody": "Transfer 200 DKK to Account XYZ",
"mitidLoa": "SUBSTANTIAL"
},
"callbackUrls": {
"success": "https://example.com/success?sessionId=a993cc3a-cad8-f041-ae83-351a55ca5202",
"abort": "https://example.com/abort?sessionId=a993cc3a-cad8-f041-ae83-351a55ca5202",
"error": "https://example.com/error?sessionId=a993cc3a-cad8-f041-ae83-351a55ca5202"
},
"environment": {
"ipAddress": "192.0.2.0",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
},
"allowedProviders": [
"mitid"
],
"flow": "redirect",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"mitidHasCpr",
"mitidReferenceTextBody",
"mitidCprSource",
"mitidNameAndAddressProtection",
"mitidIal",
"mitidLoa",
"mitidAal",
"mitidFal",
"mitidUuid"
],
"sessionLifetime": 1200,
"expiresAt": "2024-11-18T09:06:07.4162996+00:00"
}
Status overview
What you need to do with the response
If the returned status is SUCCESS, you will find information about the authenticated user in the subject object.
You will also see what identity provider was actually used by checking the provider field. This can be useful if you allowed more than one identity provider when you created the session.
You have now completed an authentication flow with MitID.
Next steps
Learn more about available request and response attributes for MitID:
Dive deeper into Authentication REST API and improve your application with advanced security features: