Skip to main content

restapi

Authentication REST API

The Authentication REST API allows you to connect to the eID and Wallet Hub and perform end-user identity verification and authentication through a REST API, where all request and response bodies are formatted in JSON.

Initial preparation

The Authentication REST API supports the OAuth 2.0 client credentials grant flow: you first exchange a client ID and a secret for an access token, then use the access token to authenticate the requests to the API endpoints.

To learn how to connect to this API, follow steps 1-3 in the Connect to Signicat APIs Quick start guide.

What permissions are required?

Ensure that you set permission Authentication REST API for your API client.

Import the Postman collection

To make calls to the Authentication REST API, we created a Postman collection. Note that Postman is a tool for learning and testing APIs, therefore you should not use Postman in your application in production.

You can fork or import the Postman collection by clicking the button below:

Run In Postman

To start using the Postman collection, do the following:

  1. Fork or import the Postman collection.
  2. Open Postman and select the Signicat Authentication REST API collection.
  3. In the Variables tab, edit the following variables:
    • baseURL: Enter the base URL of the API. Set this to: https://api.signicat.com/auth/rest.
    • oauth_scope: Enter the scope you want to work with. Set this to: signicat-api.
    • oauth_client_id: Enter the client ID (for example dev-red-pin-123) of your API client.
    • oauth_client_secret: Enter the client secret associated to your API client.
    • oauth_url: Enter the Authorisation URL. Set this to: https://api.signicat.com/auth/open/connect/token.
  4. Click the (save) icon or type Ctrl+S.

Now, you are ready to obtain an access token using the variables you defined above.

Obtain an access token

To authorise requests to the API, you need to send an access token in your request. To obtain the access token with the Postman collection, do the following:

  1. Select the Authorization tab.
  2. Scroll to the bottom and select Get New Access Token.
  3. If the request was successful, review the Access Token and select Use Token.

You have now obtained a token to authenticate to the API. When calling an API endpoint, you supply the access token in the HTTP Authorization header of your request. You can always review your token in Authorization > Token.

Note: Tokens have a default expiry date. If a token expires, repeat the steps above to request a new token.

Create an authentication session

To begin an authentication flow, your app needs to direct the end-user to an eID, such as Norwegian BankID. To obtain the authorization URL where to redirect the end-user to authenticate, you send a POST request to the Create a new session endpoint with the appropriate parameters in the body of the request.

The body of the request might look like this:

{
  "flow": "redirect",
  "requestedAttributes": [
    "name",
    "dateOfBirth",
    "nin",
  ],
  "callbackUrls": {
    "success": "https://example.com/success",
    "abort": "https://example.com/abort",
    "error": "https://example.com/error"
  },
  "allowedProviders": [
    "nbid"
  ],
}

To begin an authentication flow using the Postman collection, do the following:

  1. In the left menu, expand the collection and select the Create a new session endpoint.
  2. In the endpoint window, select Send to send the request.
  3. In the response window, select the Body tab to view the response payload.
  4. Copy and paste the authenticationUrl link in your browser to start an authentication session with the eID. In this case, Norwegian BankID.

When adding login to your application, you will redirect the end-user to the authenticationUrl.

Authenticate the end-user

You need a test user to complete the authentication. For example, you can use the following credentials for Norwegian BankID:

After completing the authentication flow, you can retrieve the response from successful authentication.

Get the authentication session status

When using the API, you can check the status of the authentication session at any stage. When the end-user authenticates successfully, you receive the user data attributes in the response. To do this:

  1. In the left menu, expand the id folder and open the Get session status endpoint.
  2. To check the session status, select Send. This sends an HTTP GET request using the session ID obtained from the Create a new session endpoint.
  3. Inspect the response in the Body tab of the response window.

If the authentication was successful ("status": "SUCCESS"), you find the end-user data attributes in the subject field.

You have now completed an authentication flow using the Authentication REST API!

Next steps

This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about the Authentication REST API and exploring the eIDs documentation.

Authentication REST API
Find out more about the Signicat Authentication REST API which enables you to easily and securely authenticate your end-users.
Supported eIDs
View and learn how to integrate with the eIDs

For information about the available endpoints and properties, as well as sample requests and responses, see the Authentication REST API reference:

Authentication REST API
Configure your Authentication REST API