Skip to main content

Authentication REST API

This guide shows you how to integrate with Freja using Signicat Authentication REST API as an authentication protocol.

Prerequisites​

  1. Follow the steps on the Initial preparations page to establish a connection with Freja.

    1. 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.

      Want to learn more?

      To learn more about the Signicat Authentication REST API, see:

Implement the authentication flow​

1. Build the authentication request (CreateSession)​

This section describes how to make an HTTP POST request to the /sessions endpoint, to create a session and start an authentication.

To begin the authentication flow, your application must first start a session by utilising the /sessions endpoint. The endpoint automatically creates 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 contains an authentication URL, to which you can embed in an iframe and present to 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 Freja authentication, where the minimum registration level is EXTENDED and all available attributes are requested:

{
    "flow": "redirect",
    "allowedProviders": [
        "freja"
    ],
    "requestedLoa": "SUBSTANTIAL",
    "additionalParameters": {
        "freja_min_registration_level": "EXTENDED"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "fullName",
        "dateOfBirth",
        "nin",
        "email",
        "phoneNumber",
        "address",
        "idpId",
        "frejaRegistrationLevel",
        "frejaAge",
        "frejaAllPhoneNumbers",
        "frejaAllEmailAddresses",
        "frejaAllAddresses",
        "frejaRelyingPartyUserId",
        "frejaIntegratorSpecificUserId",
        "frejaDocumentData"
    ],
    "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 Freja.

If the authentication completes successfully, the final result will contain the attributes that were requested.

Attribute descriptions​

To initialise an authentication with Freja, you can use the following attributes in the initial request:

For more detailed field descriptions, see the API reference.

Control the Freja flow (additionalParameters)​

You can control the Freja flow by using the additionalParameters.

Available parameters and values are:

User attributes (requestedAttributes)​

You can request the following attributes from users of Freja.

You add them in the requestedAttributes as shown in the request example above.

Response example​

Here is a CreateSession response example:


{
    "id": "d64e1b7c-960a-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=00eaba1f-5a58-9449-a409-15035cd9cfb3&transactionId=d64e1b7c-960a-dd48-a736-f513b06c88c2",
    "status": "CREATED",
    "callbackUrls": {
        "success": "http://example.com/success?sessionId=d64e1b7c-960a-...",
        "abort": "http://example.com/abort?sessionId=d64e16b7c-960a-...",
        "error": "http://example.com/error?sessionId=d64e1b7c-90a-..."
    },
    "allowedProviders": [
        "freja"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "fullName",
        "dateOfBirth",
        "nin",
        "email",
        "phoneNumber",
        "address",
        "idpId",
        "frejaRegistrationLevel",
        "frejaAge",
        "frejaAllPhoneNumbers",
        "frejaAllEmailAddresses",
        "frejaAllAddresses",
        "frejaRelyingPartyUserId",
        "frejaIntegratorSpecificUserId",
        "frejaDocumentData"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2024-08-12T12:00:55.3285274+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 Freja authentication in context of the session you just created.

"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=00eaba1f-5a58-9449-a409-15035cd9cfb3&transactionId=d64e1b7c-960a-dd48-a736-f513b06c88c2"

End-user authentication​

The end-user follows these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with Freja. Your application sends a request to start an authentication with Freja, as described in the previous section.
  2. The end-user is redirected to the Freja login page.
  3. The end-user logs in using their Freja credentials (this step may involve two-factor authentication).

After the end-user approves the request, the browser is redirected back to the relevant callbackUrl specified in the CreateSession request.

For screen examples, see About Freja.

2. Obtain user information (GetSession)​

Make an HTTP GET request to the /sessions endpoint to poll for information regarding the session and ongoing authentication.

Upon successful authentication, a response is returned that contains the user information requested in the "Create a new session" call carried out earlier.

Request​

No data specific for Freja 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": "d64e1b7c-960a-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=39ea...",
    "status": "SUCCESS",
    "provider": "freja",
    "subject": {
        "id": "-DvPAh0W...",
        "idpId": "0A4724BF...",
        "name": "Sven Svensson",
        "firstName": "Sven",
        "lastName": "Svensson",
        "dateOfBirth": "1990-02-17",
        "email": "test@example.com",
        "nin": {
            "value": "199002171234",
            "issuingCountry": "SE",
            "type": "PERSON"
        },
        "phoneNumber": "+46701740605",
        "frejaRegistrationLevel": "EXTENDED",
        "frejaRelyingPartyUserId": "0A4724B...",
        "frejaIntegratorSpecificUserId": "880A680...",
        "frejaAllPhoneNumbers": "[{\"phoneNumber\":\"+46701740605\"}]",
        "frejaAllAddresses": "[{\"country\":\"SE\",\"address\":\"ANEBYVÄGEN 61\",\"city\":\"STOCKHOLM\",\"postCode\":\"11148\",\"type\":\"RESIDENTIAL\"},{\"country\":\"SE\",\"address\":\"AMINOGATAN 91\",\"city\":\"STOCKHOLM\",\"postCode\":\"10338\",\"type\":\"POSTAL\"}]",
        "frejaAllEmailAddresses": "[{\"emailAddress\":\"test@example.com\"}]",
        "frejaAge": "34",
        "frejaDocumentData": "{\"country\":\"SE\",\"serialNumber\":\"258017186\",\"type\":\"PASS\",\"expirationDate\":\"2029-06-11\"}",
        "address": "AMINOGATAN 91, 10338, STOCKHOLM, SE",
        "addressFormatted": {
            "FullAddress": "AMINOGATAN 91, 10338, STOCKHOLM, SE",
            "Street": "AMINOGATAN 91",
            "City": "STOCKHOLM",
            "PostalCode": "10338",
            "Country": "SE"
        }
    },
    "callbackUrls": {
        "success": "http://example.com/success?sessionId=d64e1b7c-960a-...",
        "abort": "http://example.com/abort?sessionId=d64e16b7c-960a-...",
        "error": "http://example.com/error?sessionId=d64e1b7c-90a-..."
    },
    "environment": {
        "ipAddress": "192.0.2.0",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
    },
    "allowedProviders": [
        "freja"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "address",
        "email",
        "firstName",
        "frejaAge",
        "frejaAllAddresses",
        "frejaAllEmailAddresses",
        "frejaAllPhoneNumbers",
        "frejaDocumentData",
        "frejaIntegratorSpecificUserId",
        "frejaRegistrationLevel",
        "frejaRelyingPartyUserId",
        "fullName",
        "lastName",
        "name",
        "nin",
        "phoneNumber",
        "idpId"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2024-08-13T08:41:43.9625942+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.

Success

You have now completed an authentication flow with Freja.

Next steps​

Learn more about available request and response attributes for Freja:

Attributes reference
Look up available attriutes for Freja

Dive deeper into Authentication REST API and improve your application with advanced security features:

Signicat Authentication REST API
Find out more about available flows in the eID Hub documentation
API reference
Look up endpoint and parameter details in the reference guide
On this page