Authentication

Trace One APIs accept only tokens from the OAuth 2.0 client credentials flow, issued to your application. A token issued to a person (someone signed in to a Trace One application) is refused with 401.

Get a token


Token URL	`https://ws-users.traceone.com/default/connect/token`
Grant type	`client_credentials`
Scope	`t1_api` (the only scope)

POST https://ws-users.traceone.com/default/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=t1_api

Response:

{
  "access_token": "eyJhbGci...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "t1_api"
}

Send the token in the Authorization header of every call:

Authorization: Bearer eyJhbGci...

Keep and renew the token

Reuse the token for all your calls until it expires. Do not request a token per call.
Read expires_in (seconds) from the response. Do not hard-code the lifetime.
Renew it early, for example one minute before it expires.
On a 401, request a new token and retry the call once. If the call fails again, stop and check your credentials.

import time
import requests

TOKEN_URL = "https://ws-users.traceone.com/default/connect/token"
_token = {"value": None, "expires_at": 0}

def get_token():
    if _token["value"] and time.time() < _token["expires_at"] - 60:
        return _token["value"]
    response = requests.post(TOKEN_URL, data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "t1_api",
    })
    response.raise_for_status()
    body = response.json()
    _token["value"] = body["access_token"]
    _token["expires_at"] = time.time() + body["expires_in"]
    return _token["value"]

Keep the secret safe

Use the credentials on your server only. Never put them in a browser page, a mobile app or a desktop app.
Store the secret in a secret store or an environment variable, never in source control.
If the secret may have leaked, contact us to replace it.

401 and 403

Status	Meaning	What to do
`401 Unauthorized`	The token is missing, expired, invalid, or was not issued by the client credentials flow	Get a new token and retry once
`403 Forbidden`	The token is valid, but your company has no access to this resource or operation	Do not retry. Check that the resource belongs to your company or is shared with it

Next steps