# 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:
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:
- Log in to the Dashboard at dashboard.signicat.io (opens new window).
- 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".
- 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".
- On the client information screen, click "OAuth/OpenID Config", click "Edit", and select the necessary scopes under "API access".
- 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.