# Accessing Signicat API products

All of our API products have sophisticated access and identity and access management (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. In the Dashboard (opens new window), select API clients (opens new window) and click Create client.
  2. Enter a name for the client, click Create.
  3. You must have at least one client secret, so click Add secret on the next screen.
  4. Generate a client secret. Be sure to take a note of the client secret when instructed!
  5. 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.

See our documentation on Managing roles and permissions for more information.

# Obtaining an access token

In general, we recommend you use an existing library, SDK or application for any OAuth or OIDC interactions. However, note that the OAuth 2.0 client credentials flow to access our API products requires you to make only one POST request.

To get an access token, send a POST request using either of the following client authentication methods:

  • client_secret_post: to include your client credentials explicitly in the request payload.
  • client_secret_basic: to use HTTP basic authentication with your Client ID as the username and Client Secret as the password. In this case, you need to format your client credentials as a Base64-encoded string: client_id:client_secret.

Example of HTTP basic authentication header with Base64-encoded string: Authorization: Basic c2FuZGJveC1yb3VuZC1hcHBsZS0xMjM6ZmFrZUNsMTNuN1MzQ3IzVDEyMzQ1Njc4OTA=.

Token caching

Caching access tokens is the recommended way when interacting with Signicat APIs. This will help limit your network usage and resource overhead while reducing traffic to Signicat servers.

You can cache your access tokens using a memory cache, like Redis or simple in-memory cache, and renew the tokens when they get close to the token expiration time.

If tokens fail, configure your application to retry the request one more time.

# 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

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 Signicat API products, refer to the API documentation or directly to the product documentation.

Last updated: 20/03/2024 10:00 UTC