Skip to main content

Implement with the Signicat REST API

This guide shows you how to authenticate end-users with SIAM, using the Signicat Authentication REST API with redirect flow.

Want to learn more?

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

Prerequisites​

  1. Follow the steps to Configure SIAM.

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

Redirect flow​

This guide shows how to set up authentication using the redirect flow. The redirect flow allows you to pass an authorization URL to your end-users that they can open in a browser to follow an identity verification flow with SIAM.

1. Create a session​

Request​

To create a session using the Authentication REST API, you need to send a POST request to the Create a new session endpoint.

Endpoint URL: https://api.signicat.com/auth/rest/sessions

For example, you can build your request like this:

POST /auth/rest/sessions HTTP/1.1
Host: api.signicat.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
    "allowedProviders": [
        "ownidp"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "firstName",
        "lastName",
        "fullName",
        "middleName",
        "gender",
        "dateOfBirth",
        "company",
        "street",
        "houseNumber",
        "houseNumberSuffix",
        "city",
        "region",
        "postalCode",
        "country",
        "fullAddress",
        "phoneNumber",
        "ninValue",
        "ninType",
        "ninIssuingCountry",
        "custom_member_id"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    },
    "requestDomain": "<YOUR_SIGNICAT_DOMAIN>"
}

Note the following fields in the payload of the request:

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

Response​

If the request is successful, you will receive a response containing the session ID and the authenticationUrl:

{
    "id": "ab31ed7-b5cb-402e-a989-dcf1d0f7f557",
    "accountId": "a-spge-zRW...XB",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=0ef7112f-d292-b042-a289-e42b66f02424&transactionId=3f7ea0c8-97ae-c547-ad5f-a62492ceb0a2",
    "status": "SUCCESS"
}

2. Redirect the user​

Redirect the user to the authenticationUrl returned in the response. The user will be redirected to the SIAM login screen where they can log in.

3. Retrieve session data​

After the user successfully authenticates, they are redirected back to the success callback URL. You can then retrieve the user attributes by sending a GET request to the session endpoint:

Endpoint URL: https://api.signicat.com/auth/rest/sessions/{id}

Response Example​

The following is an example of a response showing the end-user information attributes:

{
    "id": "ab31ed7-b5cb-402e-a989-dcf1d0f7f557",
    "accountId": "a-spge-zRW...XB",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=0ef7112f-d292-b042-a289-e42b66f02424&transactionId=3f7ea0c8-97ae-c547-ad5f-a62492ceb0a2",
    "status": "SUCCESS",
    "provider": "ownidp",
    "subject":
    {
        "id": "qyIsCvjlb-UQAjOaH2JJXFXtZj4eXECrTrsexxpBOEI=",
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "John Robert Doe",
        "middleName": "Robert",
        "gender": "male",
        "dateOfBirth": "1985-06-15",
        "company": "Signicat AS",
        "street": "Munkegata",
        "houseNumber": "26",
        "houseNumberSuffix": "B",
        "city": "Trondheim",
        "region": "Trøndelag",
        "postalCode": "7011",
        "country": "Norway",
        "fullAddress": "Munkegata 26B, 7011 Trondheim, Norway",
        "phoneNumber": "+4799999999",
        "ninValue": "15068512345",
        "ninType": "social_security_number",
        "ninIssuingCountry": "NO",
        "custom_member_id": "M12345"
    },
    "callbackUrls":
    {
        "success": "https://example.com/success?sessionId=ab31ed7-b5cb-402e-a989-dcf1d0f7f557",
        "abort": "https://example.com/abort?sessionId=ab31ed7-b5cb-402e-a989-dcf1d0f7f557",
        "error": "https://example.com/error?sessionId=ab31ed7-b5cb-402e-a989-dcf1d0f7f557"
    }
}

SIAM REST API attributes​

See the REST API parameters that apply to SIAM:

Attributes reference
Attributes and examples for SIAM with Authentication REST API
On this page