Authentication

The External API accepts exactly one grant: OAuth2 client credentials. Every caller is a service account acting for one organization — there is no user-interactive flow, no API keys and no refresh tokens.

Getting credentials

A client id and secret are issued for your organization by Secutec. Contact your customer-success representative or support to have credentials issued or rotated. Store the secret like any other production secret — it grants access to your organization's security data.

Requesting a token

Request an access token from the platform's token endpoint:

POST https://auth.my.secutec.com/realms/secutec/protocol/openid-connect/token

curl -s \
  -d "grant_type=client_credentials" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  https://auth.my.secutec.com/realms/secutec/protocol/openid-connect/token

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Send the token on every request:

Authorization: Bearer <access_token>

Token lifetime

Access tokens are valid for 5 minutes and no refresh token is issued. When a token expires, request a new one with the same credentials. A robust client either tracks expires_in and re-requests shortly before expiry, or simply reacts to a 401 with type .../auth/expired-token by fetching a fresh token and retrying once.

Do not request a new token per API call — reuse a token for its lifetime.

Scope of a token

The token carries your organization context. Every response is scoped to your organization automatically:

• There is no organization id to pass in a path, query or body — and none is accepted.
• Credentials cannot be shared across organizations. If you operate several organizations, each has its own credentials.

Authentication errors

Status	type suffix	Meaning
401	auth/missing-token	No Authorization header was sent.
401	auth/invalid-token	The token is malformed or its signature does not verify.
401	auth/expired-token	The token's 5-minute lifetime has passed — request a new one.
401	auth/revoked-account	The service account has been disabled.
403	auth/insufficient-role	The token is valid but lacks the role the endpoint requires.

All error bodies follow the same problem-document format — see Errors.