API Authentication

Last updated 4 months ago

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.

Endpoint

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

Use this endpoint for both test and production environment.

1) Obtaining an access token

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

Parameters

The request must include the following 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.idfy.io/oauth/connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0
grant_type=client_credentials
scope=document_read

Note: 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 retrieve 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 endpint

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@idfy.io

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"
}

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