@spec scopes(ArchAstro.Client.t()) ::
  {:ok, ArchAstro.Types.Operations.GetOauthScopes.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List available OAuth scopes

Returns the complete set of OAuth scopes that the platform supports. Use this endpoint to discover which scopes are available before constructing an authorization request or rendering a consent UI.

No authentication is required. The response is the same for all callers.

Successful response

@spec token(ArchAstro.Client.t(), ArchAstro.Types.Operations.PostOauthToken.Input.t()) ::
  {:ok, ArchAstro.Types.OAuthTokenResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Exchange a grant for OAuth tokens

Issues an access token and a refresh token in exchange for a valid grant. Three grant types are supported: "authorization_code", "refresh_token", and "urn:ietf:params:oauth:grant-type:device_code".

For "authorization_code" grants, supply code, client, redirect_uri, and optionally code_verifier for PKCE flows. Each authorization code is single-use; consuming it a second time returns invalid_grant.

For "refresh_token" grants, supply refresh_token. The endpoint rotates the refresh token on every call and returns a fresh pair of tokens.

For device-code grants, supply device_code and client. Poll this endpoint after receiving authorization_pending until the user approves or the code expires. Slow down polling if you receive slow_down.

This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding the limit returns HTTP 429 with "error": "too_many_requests".

Token pair issued for the authenticated user.