# Connecting to the API

To access our APIs you need to authenticate with the Oauth 2.0 standard. OAuth2 is an open protocol to allow secure authorisation in a simple and standard method from web, mobile, and desktop applications.

To connect to the API you need to have an account set up. If you don't have one, you can go ahead and create a test account now:

Create test account

This is the endpoint used for both test and production environments:

https://api.signicat.io/oauth/connect/token

Deprecated endpoint

If you have an older integration, you might be using https://api.idfy.io/oauth/connect/token instead. That's fine for now! However, don't use this endpoint under any other circumstances, since it's being deprecated.

# How to create an API client

When your Dashboard account is created, it will include a default OAuth client. However, you may want to create a new client at some point. If so, this is how you do it:

  1. Log in to the Dashboard at dashboard.signicat.io (opens new window).
  2. Click "Account", and then "API Clients". If you have access to more than one account, click "Account" > "View account", search for the account you want to edit, and click "API Clients".
  3. Click "New client", give the new client a name and copy the client secret (make sure you keep it safe, since you won't be able to see it again). Then, click "Create".
  4. On the client information screen, click "OAuth/OpenID Config", click "Edit", and select the necessary scopes under "API access".
  5. Click "Save".

# About scopes

The required scopes will vary depending on the API endpoints you want to use. A complete list can be found in our API Reference​.

Our most used scopes are:

scope Endpoint Access level
document_read signature Read access to documents
document_write ​signature​ Write access to documents
document_file ​signature​ Download files (signed and unsigned)
event ​notification​ Full access to notification endpoint
identify ​identification ​Read/write access to identification endpoint

# Step 1: Open Postman (or a similar tool)

Our developers like to use Postman, which allows you to easily send requests. It can be downloaded for free from the Postman website (opens new window).

You can also download the OpenAPI document for our APIs from our API Reference​ (click the "Download" button at the top of the page).

# Step 2: Obtain an access token

To obtain the access token, make a request to the OAuth2 token endpoint. Use these parameters:

Parameter Value
grant_type The type of grant used to authenticate the request. In this case: client_credentials.
scope Space-delimited list of requested scope permissions. See information about scopes above.

Note: The client you are using must be set up with the correct scopes to be able to return an access token. If the response says invalid scope, edit your API client in the dashboard (test environment / production environment) or contact support@signicat.com.

# Example

POST https://api.signicat.io/oauth/connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0

grant_type=client_credentials
scope=document_read

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 base-64 encoded string client_id:client_secret

Client ID and client secret

To find your Client ID and Client Secret, log in to the Dasboard, go to API Clients > Oauth clients, and select the client you want to use.

# Response

If your credentials are valid, the server will respond with a JSON body containing the access token and its expiration time:

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

# Step 3: Use the obtained token

You can now store and use the access token to make authenticated request by passing it as an authentication header:

Authorization: Bearer xxxxx.yyyyy.zzzzz

# Reusing a token

You should use the same token as long as it is valid. In the response containing the access token, a property called expires_in is included. This value indicates for how many seconds the token is valid for after its creation.

When the token is (nearly) expired, you should fetch a new one following the same procedure as before, and store it to some kind of caching for reuse. As soon as the token expires, it will no longer be usable.

# Troubleshooting

# API returns 403 Forbidden

This means that your token does not include the required scope.

# API returns 401 Unauthorised

This means that your token has expired or is missing from the request.

Last updated: 20/07/2023 13:13 UTC