Skip to main content

Quick start guide

Learn how to set up a connection to any Signicat API.

This quick start guide shows you how to:

  1. Complete the initial preparations, if required.
  2. Create an API client in the Signicat Dashboard.
  3. Set permissions for your API client.
  4. Request an access token using your API client credentials.
  5. Use the access token to make an API request. Make your first request to an API.
Authorisation flow sequence diagram

Sequence diagram showing the authorisation flow for Signicat APIs

1. Initial preparations​

To use any Signicat API in your applications, you first need to sign up to the Signicat Dashboard. This allows you to configure an account, create API credentials and manage products.

Before you start, make sure you have:

Sandbox and production accounts

We recommend that you create a sandbox account to test our services before going live. You must set up sandbox and production accounts separately.

2. Get client credentials​

To authenticate against our APIs, you need to set up an API client with scope signicat-api. An API client consists of a client_id/client_secret pair.

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

  1. Go to Signicat Dashboard > Settings > API clients.
  2. Select + Add client.
  3. Enter a name for the client, then select Create.
  4. You must have at least one client secret, so select Add secret to create one. This takes you to the Secrets tab on the client details page.
  5. Select + Add secret to create a secret.
  6. Enter a name for the client secret, then select Generate secret.
Store the client secret

Make sure that you store the client secret in a secure place. This is the only time that you can view the client secret in clear text.

If you do lose your client secret, then you can always generate another one.

Find the client ID

An API client has an associated client ID visible in the client overview. For example, this could look something like dev-round-apple-123.

3. Set permissions​

To complete the API client setup, you need to add the correct permissions for the API products that you intend to connect to with the client. To do this:

  1. Go to Signicat Dashboard > Settings > API clients.
  2. Select Edit next to the API client that you created.
  3. On the API client page, navigate to the Permissions tab.
    Note

    If you cannot access the Permissions tab, then you do not have the correct role to manage permissions for your organisation. To receive access, contact your organisation administrator or us by creating a support ticket in the Signicat Dashboard..

  4. Select + Select product.
  5. Tick the box corresponding to the API product that you intend to use with this API client, then select Update to save the changes.

What permissions are required?​

You can use the table below to determine what permissions you need to set for the API product that you want to connect to:

Advanced permissions

You can manage advanced access to resources by assigning specific roles to your API (machine) clients. For more information, see the Managing roles and permissions page.

4. Obtain an access token​

You can now use the API client credentials to obtain an access token. To do this, you need to send a POST request using either of the following client authentication methods:

  • Explicit credentials (client_secret_post)
  • HTTP basic authentication (client_secret_basic)

The table below shows an overview of the parameters required to build a request:

What tools can I use?

You can obtain an access token using cURL, Postman, Node.js, Python, .NET, or whichever SDK or library you prefer. However, note that the OAuth 2.0 client credentials flow requires you to make only one POST request.

  1. Make a request using either of the client authentication methods:

    To obtain an access token using the client_secret_post authentication flow, you need to include your client credentials explicitly in the request payload.

    Example: Request for access token
    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'
  2. If the request is successful, then a token response is returned to you. For example:
    Example: Response with access token
    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"
    }
    Token settings

    The default access token lifetime is set to 600 seconds. For more information about token lifetime and caching, see the Access tokens page.

5. Make an API request​

Now that you have a valid access token, you can start making requests to your chosen Signicat API. To do this, you need to include the access token in the HTTP Authorization header with the Bearer scheme

For example, the request below shows what a call to the Authentication REST API could look like:

Example: Request to Authentication REST API
GET /auth/rest/sessions/{id} HTTP/2
Host: api.signicat.com
Accept: application/json
Authorization: Bearer eyJh ... QifQ.eyJ ... hIOw
HTTP requests

Incoming HTTP requests to all of our APIs must meet specific requirements. For more information, see the HTTP request requirements page.

Next steps​

For more specific information on how to use Signicat API products, see our API reference or product documentation:

Signicat APIs
Explore all Signicat API references
Signicat products
Browse all Signicat products
Advanced API connection settings

To learn about how to manage advanced API connection settings such as token lifetime and HTTP request requirements, see the Advanced settings page.

On this page