# Connecting to the API

To access our API's you need to authenticate with the Oauth 2.0 standard. OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. Be sure to use client_credentials as grant type when connecting.

Test account

To connect to the API you need to have an account set up – Create a free test account!

# Endpoint

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

Use this endpoint for both test and production environment.

Deprecated endpoint

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

# Step 1: Obtaining an access token

An access token can be obtained by making a request to the OAuth2 token endpoint

# 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.

# 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

# Scopes

When you create the access token you have to set which scopes you need, our API-enpoints requires different scopes.

A complete list can be found in our API Reference​.

Our most used scopes:

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

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 please edit your api client in our dashboards: test environment / prod environment or contact support@signicat.com

# 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 2: 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 is expired it will no longer be usable.

# How to create an API client

  1. Log in to the Dashboard at dashboard.signicat.io.
  2. Click “Account”, and then “API Clients”.
  3. Click “New client” and select the “OAuth” option. Then, give the new client a name and click “Create”.
  4. On the client information screen, click “Edit”, then “Show advanced settings”, and select the necessary scopes.
  5. Click “Save”.

# Troubleshooting

# API returns 403 Forbidden

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

# API returns 401 Unauthorized

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

Last updated: 9/11/2020, 7:51:24 AM