Authentication and Access Tokens

Exchange your client ID and client secret for a short-lived access token, and send that token with every Scrut API request.

The Scrut API uses the OAuth 2.0 client credentials grant. Your integration exchanges a client ID and client secret for a short-lived access token, then sends that token with every /v1 request.

Credentials and Tokens

Authentication uses two layers:

Item	What it is	Lifetime
API credential	A client ID and client secret that an Org Admin creates in the Developer Console	12 months, never, or a custom date. Ends early if revoked.
Access token	A Bearer token your integration requests with the credential	One hour

To create, store, or revoke a credential, see Create API Credentials.

Important: Never commit credentials to version control or expose them in client-side code.

Get an Access Token

Send a POST request to /oauth/token with a JSON body. The token endpoint accepts application/json only, not application/x-www-form-urlencoded.

curl -X POST https://api.scrut.io/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$SCRUT_CLIENT_ID"'",
    "client_secret": "'"$SCRUT_CLIENT_SECRET"'"
  }'

const tokenResponse = await fetch("https://api.scrut.io/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.SCRUT_CLIENT_ID,
    client_secret: process.env.SCRUT_CLIENT_SECRET,
  }),
});

const { access_token } = await tokenResponse.json();

import os
import requests

token_response = requests.post(
    "https://api.scrut.io/oauth/token",
    json={
        "grant_type": "client_credentials",
        "client_id": os.environ["SCRUT_CLIENT_ID"],
        "client_secret": os.environ["SCRUT_CLIENT_SECRET"],
    },
)

access_token = token_response.json()["access_token"]

Request Body

Field	Required	Value
`grant_type`	Yes	Always `client_credentials`
`client_id`	Yes	The client ID from your API credential
`client_secret`	Yes	The client secret from your API credential

Token Response

A successful request returns the token object:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "control:read, evidence:read, framework:read, policy:read, test:read, vulnerability:read"
}

Field	Description
`access_token`	The token to send in the `Authorization` header
`token_type`	Always `Bearer`
`expires_in`	Seconds until the token expires
`scope`	The scopes granted to your credential, as a comma-separated string. See Scopes and Permissions.

The token endpoint returns the standard OAuth token object. It doesn't use the { data, meta } envelope that /v1 endpoints use.

Send the Token

Include the token as a Bearer token in the Authorization header of every /v1 request:

curl https://api.scrut.io/v1/policies \
  -H "Authorization: Bearer $SCRUT_ACCESS_TOKEN"

Token Behavior

Tokens expire after 3600 seconds (one hour).
There's no refresh token. Request a new token with your credentials when the current one expires.
Several tokens from the same credential can be valid at the same time, until each one expires.
Revoking a credential invalidates all outstanding tokens.
When a credential expires, its tokens stop working, and new token requests fail. Create a new credential and update your integration before the expiry date.

Pro Tip! Reuse a token until it's close to expiring instead of requesting a new one for every call. The token endpoint allows 10 requests per 60 seconds per credential. See Rate Limits.

Authentication Errors

Error code	Returned by	What to do
`invalid_request`	`/oauth/token`	Check that `grant_type` is `client_credentials` and every field is present.
`invalid_client`	`/oauth/token`	Verify the client ID and secret. If the credential is revoked or expired, create a new one.
`unauthorized`	`/v1` endpoints	Check that the `Authorization` header contains a valid Bearer token.
`token_stale`	`/v1` endpoints	Request a new token.
`token_revoked`	`/v1` endpoints	The credential was revoked. Create a new credential.
`token_credential_expired`	`/v1` endpoints	The credential expired. Create a new credential.

For the full list, see Errors.

Contact support@scrut.io for further assistance.

Was this page helpful?