Retrieving and Managing Work Tokens

info

This REST API documentation is effective as of 21:00 EST, 2 April, 2023.

Retrieving a Work Token

After creating a client, you can retrieve a work token with a GET request, as shown in the script below.

More About Work Tokens

You can think of a client's subject and secret as being analagous to an account's username and password.

However, as mentioned previously, the secret is not actually your account password. It is a passcode that you supplied when you created your client.

Essentially, by submitting your subject and secret as part of the Authorization header, you are using your client to sign into the API, in order to retrieve your work token.

import base64
import json
import requests
import urllib.parse

BASE_URL = "https://account.app.certiscan.cloud/api/v1/account/worktoken/"
HEADERS_BASE = {'Content-Type': 'application/json'}

def get_token(subject, secret):
    basic_auth = base64.b64encode("{}:{}".format(subject, secret).encode('ascii')).decode('ascii')
    headers = {**HEADERS_BASE, **{"Authorization": "Basic {}".format(basic_auth)}}
    response = requests.get(
        urllib.parse.urljoin(BASE_URL, "{}/".format(subject)),
        headers=headers
    )
    return response.json()

A successful result will be similar to this:

{
    "success": true,
    "result": {
        "subject": "8ade3b80-56c8-4593-8e51-5e98c5afbbbe",
        "token": {
            "access_token": "Eyc1ffs9my3Vaki8f4YUujcMSd94qbG-LtdPMcF6PfE.Im88VL5toXcwjiKKoqfnIOg7wQtt_eugU6Gn1J3vPoE",
            "expires_in": 3599,
            "scope": "openid",
            "token_type": "bearer"
        }
    }
}

Based on the output of the example above, your Authorization header value for future requests will be Bearer plus the access_token. In other words:

"Bearer Eyc1ffs9my3Vaki8f4YUujcMSd94qbG-LtdPMcF6PfE.Im88VL5toXcwjiKKoqfnIOg7wQtt_eugU6Gn1J3vPoE"

From this point onward, the work token can function as your new auth_token. You no longer need to open dev tools and manually scrape the header value:

auth_token = "Bearer Eyc1ffs9my3Vaki8f4YUujcMSd94qbG-LtdPMcF6PfE.Im88VL5toXcwjiKKoqfnIOg7wQtt_eugU6Gn1J3vPoE"

Token Management

IMPORTANT

The work token expires every 60 minutes, and will need to be re-retrieved. Please retrieve a new token before running any scripts.

You should change the secret value for your client as necessary (i.e. if you have an internal 90-day password change policy, if the secret is compromised, etc.).

Never share your work token with other users. The token is bound to your account, and it can access all the features and services that your account can. You are responsible for actions performed using your work token. Your account ID will be associated with all actions performed using the work token.

If your work token has been compromised you can delete the client (effectively revoking tokens it had created). You should then create a new client with a different secret.

Listing Tokens

Call the work token endpoint to list the tokens associated with your account. Your account will have 1 or 0 tokens.

note

Although most CertiScan APIs support list paging, filtering and sorting, this tokens list API does not support paging or filtering.

import json
import requests
import urllib.parse

BASE_URL = "https://account.app.certiscan.cloud/api/v1/account/worktoken/"
HEADERS_BASE = {'Content-Type': 'application/json'}

def client_list(auth_token):
    headers = {**HEADERS_BASE, **{"Authorization": auth_token}}
    response = requests.get(
        BASE_URL,
        headers=headers
    )
    return response.json()

A successful result will be similar to this:

{
    "success": true,
    "results": {
        "pages": {
            "base_url":"https://account.app.certiscan.cloud/api/v1/account/worktoken/",
            "records": {
                "total": 1,
                "current": 1
            },
            "page": {
                "total": 1,
                "current": 1,
                "page_size": 1
            }
        },
        "list": [
            {
                "subject": "8ade3b80-56c8-4593-8e51-5e98c5afbbbe",
                "name": "New Name"
            }
        ]
    }
}