Skip to main content

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 Signicat Dashboard, select API clients.
  2. In the API clients page, select Add/Create client.
  3. Enter a name for the client, then select Create.
  4. You must have at least one client secret, so select Add secret on the next screen.
  5. Enter a name for the client secret, then select Generate secret.
  6. Make sure that you save the client secret! You will not be able to view the secret again.
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.

Every client comes with a client ID associated to it. You find the client ID underneath the name of your client in your client overview. A client ID looks something like dev-round-apple-123.

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

Permissions​

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

To edit the permissions of your API client, do the following:

  1. In the Signicat Dashboard, navigate to API clients and select Edit to edit your API client.
  2. In the API client page, navigate to the Permissions tab.
  3. To add permissions, select + Select product.
  4. Tick the box corresponding to the API product that you intend to use with this API client.

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. Contact your organisation administrator to receive access.

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​

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 https://api.signicat.com/auth/open/connect/token \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data 'grant_type=client_credentials' \ 
--data 'scope=signicat-api' \ 
--data 'client_id=sandbox-round-apple-123' \ 
--data 'client_secret=fakeCl13n7S3Cr3T1234567890'

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

Editing the token lifetime​

An access token has a relatively short lifetime (600 seconds by default). Once it expires, it can no longer be used. This is very important for security. To obtain a new access token, you need to send a new access token request.

You can edit the default token lifetime of your API client. To do this:

  1. In the Signicat Dashboard, navigate to the API clients.
  2. On your API client, select Edit.
  3. In the client overview page, edit the value in the Access token lifetime. You can set it between 1 and 3600 seconds.
  4. Select Update to save the changes.

Next steps​

For more specific information on how to use Signicat API products, refer to the API documentation or directly to the product documentation.

Signicat APIs
You can find all the available Signicat APIs here.
All Signicat products
Browse Signicat product offering.
Last updated:
On this page