Authentication and Authorization

Calls to the API can use HTTP Basic Authentication, or Token Authentication.

Basic Authentication

To authenticate using HTTP Basic Authentication, use the same credentials (username and password) as for normal logins in a web browser.

Token Authentication

API tokens are managed per-user. Access to manage tokens (and to obtain them via the api-token-auth endpoint) is gated by the Can Use API Tokens permission, which is set on each user in the organization team-member edit page.

Tokens are stored as one-way hashes — the full token value is shown only once at creation and cannot be recovered afterwards. If the value is lost, revoke the token and create a new one.

The token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

For example, using cURL:

curl https://www.trialgrid.io/api/v2/users/ -H 'Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b'

Managing tokens via the user profile

When the Can Use API Tokens permission is enabled, users see an API Tokens tab on their user profile from which they can create, review and revoke their own tokens. See Managing your API tokens for the user-facing flow (creating, naming, copying, revoking, email notifications, and tips on rotation).

Single Sign-On users can manage their tokens via the profile UI without re-entering a password (their active SSO session is used as authorisation). Users authenticated with a local password are prompted to re-enter their password before reaching the tab.

Obtaining a token via the API

An authentication token can also be obtained by making an HTTP POST request to api/v2/api-token-auth/, providing your login credentials in JSON data in the POST request. The user must have the Can Use API Tokens permission enabled.

For example, using cURL:

curl --header "Content-Type: application/json" --data '{"username":"USER","password":"PASSWORD"}' --request POST https://www.trialgrid.io/api/v2/api-token-auth/

The API will return a JSON string containing the token, e.g.

{"token":"fa2ae7f1c766ddea1c8b4ff14773de33569d399b"}

Note

Each successful call to api-token-auth/ mints a new token (named endpoint-XXXXXXXX). The endpoint can no longer return an existing token's value because token values are not stored. Scripts that authenticate once and cache the returned token continue to work unchanged. Scripts that re-call the endpoint at every invocation will accumulate tokens and should either cache the first token or revoke extras through the user profile.

The api/v2/api-token-auth-delete/ endpoint revokes all active tokens for the authenticated user — matching the previous "delete the user's token" behaviour for accounts that hold a single token. To revoke a single token without affecting others, use the profile UI.

For example, using cURL:

curl --header "Content-Type: application/json" --data '{"username":"USER","password":"PASSWORD"}' --request POST https://www.trialgrid.io/api/v2/api-token-auth-delete/

Authorization

Access to Drafts via the API is controlled by the same permissions as the main TrialGrid application. Drafts and Drafts objects can be retrieved by the API if the user account has access to view the Project.