API Authentication Reference

AlloyScan uses OAuth 2.0 client_credentials grant for service-to-service authentication. Every REST API consumer is represented by an App registration that holds a Client ID and a Client secret; you exchange those credentials for a short-lived bearer token, then attach the token to every API request.

Prerequisites

An App registration on the target site, with Enabled = true and an Expiration date in the future. See How to Register an API Application and App Registrations Reference.
The Client secret captured at creation time. AlloyScan displays the secret once; if it is lost, the registration must be replaced.

Token endpoint

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

Request body

Field	Required	Description
`grant_type`	yes	Must be `client_credentials`
`client_id`	yes	The Client ID issued at App-registration creation (system-generated, 20 characters)
`client_secret`	yes	The Client secret issued at App-registration creation (shown once)
`scope`	optional	Space-separated scope list, where applicable for your deployment

Response 200

{
  "access_token": "<opaque-bearer-token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Note: The exact expires_in value, the set of supported scopes, and the precise token-endpoint path may differ per deployment. Confirm against your instance's OpenAPI document and your AlloyScan release.

Using the token

Add the access token to every API request using the Authorization header:

GET /api/v1/devices HTTP/1.1
Host: <your-instance>.alloyservice.com
Authorization: Bearer <access_token>
Accept: application/json

All API traffic uses HTTPS. Plain HTTP is not supported.

Token lifetime and refresh

The client_credentials grant does not issue a refresh token. When the access token expires, request a new one from the token endpoint using the same Client ID and Client secret.

Important: Cache and reuse a token until it is close to expiry. Requesting a fresh token on every API call counts against your API transactions per month quota and your workload limits. See Rate Limits.

Expiration of the App registration itself

App registrations have their own Expiration date, separate from the access token lifetime:

30 days before expiry, AlloyScan begins firing the Administrative notification template.
7 days before expiry, a second reminder notification is sent.
After the Expiration date passes, every page in the AlloyScan UI shows a persistent red API client alert banner, and tokens issued from that registration stop working.

Renew or replace the App registration before it expires. See App Registrations Reference.

Failure modes

Symptom	Likely cause	Resolution
`invalid_client` on the token endpoint	Client ID typo, Client secret typo, or `Enabled = false`	Verify the registration is enabled; reissue the secret if it was lost
Token request succeeds but API calls return `401`	Token expired, or registration disabled / expired between issue and use	Request a fresh token; confirm the registration status
API calls return `403`	The token is valid, but the registration lacks the required scope or site binding	Review the registration on `Admin Center > Site Settings > IAM > App registrations`

Note: Audit-related calls performed by an integration count against the same API transactions per month quota as ad-hoc calls. The recharge-day reset applies on the site's Recharge day.