Authorization¶

Every API request carries an access token in the Authorization header:

Authorization: Bearer {access_token}

Credentials¶

Contact us to get a client ID and client secret. Your client is given the scopes it needs when it is set up. Keep the secret out of source repositories and anything that runs on your users' devices.

Scopes¶

Each scope covers only what it says: portal/write doesn't include reading. An app that creates signing processes and also reads their status or downloads their documents needs both portal/read and portal/write.

Getting a token¶

POST /api/v1/auth/token, with a form-encoded body (application/x-www-form-urlencoded):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

import requests

API = "https://api.esigna.is/api/v1"

def get_token(client_id: str, client_secret: str) -> dict:
    r = requests.post(f"{API}/auth/token", data={
        "client_id": client_id,
        "client_secret": client_secret,
        "scope": "portal/read portal/write",
    })
    r.raise_for_status()
    return r.json()

1
2
3
4
5

curl https://api.esigna.is/api/v1/auth/token \
  --request POST \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode 'scope=portal/read portal/write'

Response¶

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

expires_in is how many seconds the token is valid for. Reuse the token until shortly before then, and get a new one when it runs out; don't request a token for every call.

Errors¶