@spec approve(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostOauthDeviceApprove.Input.t()
) ::
  {:ok, ArchAstro.Types.DeviceAuthorizationStatusResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Approve a device authorization request

Grants the pending device authorization identified by user_code, completing the OAuth Device Authorization flow on behalf of the authenticated user. Once approved, the device can exchange the device_code for an access token.

Requires a valid user session — the request must be authenticated as an end user, not a machine client. The user_code must belong to a pending (not expired, not already approved or denied) authorization associated with the calling app.

If the requested scopes include a thread-scoped permission, you must supply the thread parameter; omitting it returns a 400 with error: "invalid_scope".

Confirmation that the device authorization was approved. The status field will be "approved".

@spec authorize(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostOauthDeviceAuthorize.Input.t()
) ::
  {:ok, ArchAstro.Types.DeviceAuthorizationResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Initiate a device authorization request

Starts the OAuth 2.0 Device Authorization flow for a device that cannot perform browser-based redirects. Returns a device_code (used by the device to poll for a token) and a user_code (shown to the user to enter at the verification_uri).

This endpoint requires a publishable API key; secret keys are rejected with a 403. Third-party OAuth must be enabled on the app; if it is not, the response returns error: "third_party_oauth_not_enabled" with a 403.

The endpoint is rate-limited to 10 requests per IP per minute. Excess requests receive a 429 response. The returned codes expire after expires_in seconds; once expired, a new authorization request must be initiated.

Device authorization codes and polling parameters. Present the user_code to the user and direct them to verification_uri. Poll the token endpoint using device_code at the rate given by interval.

@spec deny(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostOauthDeviceDeny.Input.t()
) ::
  {:ok, ArchAstro.Types.DeviceAuthorizationStatusResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Deny a device authorization request

Rejects the pending device authorization identified by user_code, preventing the device from obtaining an access token. Once denied, the device will receive an access_denied error on its next token poll.

Requires a valid user session. The user_code must belong to a pending authorization associated with the calling app. Attempting to deny an already approved, already denied, or expired authorization returns a 400.

Confirmation that the device authorization was denied. The status field will be "denied".