Authentication

Getting a token

Endpoint: POST https://<school>.<platform-domain>/oauth/token
Body: application/x-www-form-urlencoded (recommended, per OAuth 2.0) or JSON, with grant_type=client_credentials.
Credentials: client_id and client_secret with HTTP Basic (recommended) or in the body.
scope (optional): space-separated scopes. Empty means every scope of the connection.

The response carries Cache-Control: no-store. Call the API with Authorization: Bearer <access_token>.

Scope	Grants read access to
`https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly`	Every Rostering endpoint
`https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly`	Every Rostering endpoint
`https://purl.imsglobal.org/spec/or/v1p2/scope/gradebook.readonly`	Every Gradebook endpoint

Tokens last one hour. Request a new one when it expires; there are no refresh tokens.
A token only works at the school that issued it.
When the school revokes a connection, all its tokens stop working at once.
The school can set an expiry (30, 90, 180, 365 days, or none) and limit the network addresses allowed to call.
The secret is shown only when the connection is created. If it is lost, the school presses Thay khoá (rotate) to issue a new one; the old one keeps working for 24 hours.
An access token connection (ttdn_pat_...) calls the OneRoster API directly with Authorization: Bearer, with no token request. See Portal API.

Never send the secret by chat or unencrypted email, and never commit it to source code. Keep it in the system's secret store.

Per OAuth 2.0 (RFC 6749):

HTTP	`error`	When
401	`invalid_client`	Wrong id or secret, revoked connection, or another school's connection
400	`unsupported_grant_type`	`grant_type` other than `client_credentials`
400	`invalid_scope`	A scope the connection does not have
429	`slow_down`	More than 60 token requests in 15 minutes from one network address
503	`temporarily_unavailable`	The service is briefly unavailable; retry in a few minutes