# Accessing Signicat API products

All of our API products have sophisticated access and IAM control which has been created in-house. Signicat's platform is designed to be powerful behind the scenes, but very easy to use for our customers.

Our API products are secured with access tokens which are issued by our own OIDC/OAuth solution. To obtain these tokens you will use an API Client. These API clients also have permissions attached to them. These permissions allow you to do what you want to do at that specific API.

All our API products are available at the same domain (api.signicat.com) and you always use the scope signicat-api.

# Set up an API client

  1. Log in to the Dashboard (opens new window).
  2. Select Authentication, API clients and then Create client.
  3. Enter a name for the client, click Create.
  4. You must have at least one client secret, so click Add secret on the next screen.
  5. Generate a client secret. Be sure to take a note of the client secret when instructed!
  6. Go back to the main view.

Important

Make sure you take note of the client secret. You will not able to see it in clear text again. If you lose your client secret you can always generate more.

A Client ID has also been generated for you, which you can see underneath the name of your client. It will be something like sandbox-round-apple-123.

You will use the Client ID and Client Secret to obtain access tokens.

# Permissions

To complete setup, you will need to add the correct permissions on your client for the product API(s) that you intend to use the client with.

The steps for adding permissions are as follows:

  1. Go to the main view of the client.
  2. Click on the Permissions tab.
  3. Follow the instruction to add permissions.
  4. You can now use the API client towards your chosen Signicat API product(s).

We recommend that you create one API client per API product, but this can depend on your use case or configuration.

Important

If you cannot access the Permissions tab, this means that you do not have the correct role to manage permissions for your organisation. The person who set up the organisation will automatically have been granted this role, and this person can also assign this role to other persons in the same organisation.

# Obtaining an access token

In general, we recommend you use an existing library, SDK or application for any OAuth or OIDC interactions. However, the OAuth 2.0 client credentials flow which you use to access our API products is an extremely simple operation. You only need to make one simple POST request.

This request must authenticate using HTTP basic authentication with your Client ID as the username and Client Secret as the password. The format is the Base64-encoded string: client_id:client_secret.

Example of HTTP basic authentication header: Authorization: Basic c2FuZGJveC1yb3VuZC1hcHBsZS0xMjM6ZmFrZUNsMTNuN1MzQ3IzVDEyMzQ1Njc4OTA=.

# Required Parameters

Parameter Value
grant_type client_credentials
scope signicat-api

# Putting it all together

Tip

Our examples will use cURL. You can of course use Postman, Node.js, Python, .NET -- whatever you prefer.

Example token request

curl --request POST \
  --url "https://api.signicat.com/auth/open/connect/token" \
  --header 'Authorization: Basic c2FuZGJveC1yb3VuZC1hcHBsZS0xMjM6ZmFrZUNsMTNuN1MzQ3IzVDEyMzQ1Njc4OTA=' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data scope=signicat-api \

Example token response

HTTP/2 200 OK
content-type: application/json; charset=UTF-8
cache-control: no-store, no-cache, max-age=0
{
	"access_token": "eyJh ... QifQ.eyJ ... hIOw",
	"expires_in": 600,
	"token_type": "Bearer",
	"scope": "signicat-api"
}

# Making requests to a Signicat API

Now that you have a valid access token, you can start making requests to your chosen Signicat API. To do so you only need to include your newly acquired token - an HTTP Bearer authentication header.

Example API request

GET /auth/rest/sessions/{id}?signicat-accountId={accountId} HTTP/2
Host: api.signicat.com
Accept: application/json
Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw

Token expiry

An access token has a relatively short lifetime. Once it expires, it can no longer be used. This is very important for security. You will then need to request a new one in the same manner as you requested the first one. In the Signicat dashboard you can tweak the Access token lifetime value yourself.

# Next steps

For more specific information on how to use our Signicat API products, please refer to the documentation of that API product.

Last updated: 19/04/2023 13:10 UTC