archastro.platform.v1.resources.oauth 

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: fc8f712c2ee7
  4
  5from __future__ import annotations
  6
  7from typing import Any, Required, TypedDict
  8
  9from pydantic import BaseModel, Field
 10
 11from ...runtime.http_client import HttpClient, SyncHttpClient
 12from ...types.device import (
 13    DeviceAuthorizationDetailsResponse,
 14    DeviceAuthorizationResponse,
 15    DeviceAuthorizationStatusResponse,
 16)
 17from ...types.oauth import OAuthTokenResponse
 18
 19
 20class DeviceApproveInput(TypedDict, total=False):
 21    "Approve a device authorization request"
 22
 23    thread: str | None
 24    "Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission."
 25    user_code: Required[str]
 26    "User-facing verification code shown on the device. Identifies the pending authorization to approve."
 27
 28
 29class DeviceAuthorizeInput(TypedDict, total=False):
 30    "Initiate a device authorization request"
 31
 32    client: Required[str]
 33    "OAuth client ID (`cli_...`) identifying the application requesting authorization."
 34    scope: str | None
 35    'Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.'
 36
 37
 38class DeviceDenyInput(TypedDict):
 39    "Deny a device authorization request"
 40
 41    user_code: str
 42    "User-facing verification code shown on the device. Identifies the pending authorization to deny."
 43
 44
 45class OauthTokenInput(TypedDict, total=False):
 46    "Exchange a grant for OAuth tokens"
 47
 48    client: str | None
 49    'OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.'
 50    code: str | None
 51    'Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.'
 52    code_verifier: str | None
 53    "PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise."
 54    device_code: str | None
 55    "Device code received from the device authorization endpoint. Required for device-code grants."
 56    grant_type: Required[str]
 57    'The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.'
 58    redirect_uri: str | None
 59    'Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.'
 60    refresh_token: str | None
 61    'Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.'
 62
 63
 64class OauthScopesResponse(BaseModel):
 65    """
 66    Successful response
 67    """
 68
 69    scopes: dict[str, Any] = Field(
 70        ...,
 71        description='Map of scope name to its definition object. Each key is a scope string (e.g. `"threads:read"`) and each value describes the scope\'s purpose and requirements.',
 72    )
 73
 74
 75class AsyncDeviceResource:
 76    def __init__(self, http: HttpClient):
 77        self._http = http
 78
 79    async def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
 80        """
 81        Approve a device authorization request
 82        Grants the pending device authorization identified by `user_code`, completing
 83        the OAuth Device Authorization flow on behalf of the authenticated user. Once
 84        approved, the device can exchange the `device_code` for an access token.
 85        Requires a valid user session the request must be authenticated as an end
 86        user, not a machine client. The `user_code` must belong to a pending (not
 87        expired, not already approved or denied) authorization associated with the
 88        calling app.
 89        If the requested scopes include a `thread`-scoped permission, you must supply
 90        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
 91
 92        Args:
 93            input: Request body.
 94            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
 95            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
 96
 97        Returns:
 98            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
 99        """
100        return await self._http.request(
101            "/oauth/device/approve",
102            method="POST",
103            body=input,
104            response_type=DeviceAuthorizationStatusResponse,
105        )
106
107    async def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
108        """
109        Inspect a pending device authorization
110        Returns the client name, requested scopes, and expiration for a pending
111        device authorization owned by the calling app. The caller must be an
112        authenticated user. This endpoint never approves the request.
113
114        Args:
115            code: User-facing device authorization code.
116
117        Returns:
118            Successful response
119        """
120        query: dict[str, object] = {}
121        query["code"] = code
122        return await self._http.request(
123            "/oauth/device/authorization",
124            query=query,
125            response_type=DeviceAuthorizationDetailsResponse,
126        )
127
128    async def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
129        """
130        Initiate a device authorization request
131        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
132        perform browser-based redirects. Returns a `device_code` (used by the device
133        to poll for a token) and a `user_code` (shown to the user to enter at the
134        `verification_uri`).
135        This endpoint requires a publishable API key; secret keys are rejected with
136        a 403. Third-party OAuth must be enabled on the app; if it is not, the
137        response returns `error: "third_party_oauth_not_enabled"` with a 403.
138        The endpoint is rate-limited to 10 requests per IP per minute. Excess
139        requests receive a 429 response. The returned codes expire after
140        `expires_in` seconds; once expired, a new authorization request must be
141        initiated.
142
143        Args:
144            input: Request body.
145            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
146            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
147
148        Returns:
149            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`.
150        """
151        return await self._http.request(
152            "/oauth/device/authorize",
153            method="POST",
154            body=input,
155            response_type=DeviceAuthorizationResponse,
156        )
157
158    async def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
159        """
160        Deny a device authorization request
161        Rejects the pending device authorization identified by `user_code`, preventing
162        the device from obtaining an access token. Once denied, the device will
163        receive an `access_denied` error on its next token poll.
164        Requires a valid user session. The `user_code` must belong to a pending
165        authorization associated with the calling app. Attempting to deny an already
166        approved, already denied, or expired authorization returns a 400.
167
168        Args:
169            input: Request body.
170            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
171
172        Returns:
173            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
174        """
175        return await self._http.request(
176            "/oauth/device/deny",
177            method="POST",
178            body=input,
179            response_type=DeviceAuthorizationStatusResponse,
180        )
181
182
183class AsyncOauthResource:
184    def __init__(self, http: HttpClient):
185        self._http = http
186        self.device = AsyncDeviceResource(http)
187
188    async def scopes(self) -> OauthScopesResponse:
189        """
190        List available OAuth scopes
191        Returns the complete set of OAuth scopes that the platform supports.
192        Use this endpoint to discover which scopes are available before constructing
193        an authorization request or rendering a consent UI.
194        No authentication is required. The response is the same for all callers.
195
196        Returns:
197            Successful response
198        """
199        return await self._http.request("/oauth/scopes", response_type=OauthScopesResponse)
200
201    async def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
202        """
203        Exchange a grant for OAuth tokens
204        Issues an access token and a refresh token in exchange for a valid grant.
205        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
206        and `"urn:ietf:params:oauth:grant-type:device_code"`.
207        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
208        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
209        consuming it a second time returns `invalid_grant`.
210        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
211        refresh token on every call and returns a fresh pair of tokens.
212        For device-code grants, supply `device_code` and `client`. Poll this endpoint
213        after receiving `authorization_pending` until the user approves or the code
214        expires. Slow down polling if you receive `slow_down`.
215        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
216        the limit returns HTTP 429 with `"error": "too_many_requests"`.
217
218        Args:
219            input: Request body.
220            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
221            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
222            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
223            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
224            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
225            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
226            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
227
228        Returns:
229            Token pair issued for the authenticated user.
230        """
231        return await self._http.request(
232            "/oauth/token",
233            method="POST",
234            body=input,
235            response_type=OAuthTokenResponse,
236        )
237
238
239class DeviceResource:
240    def __init__(self, http: SyncHttpClient):
241        self._http = http
242
243    def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
244        """
245        Approve a device authorization request
246        Grants the pending device authorization identified by `user_code`, completing
247        the OAuth Device Authorization flow on behalf of the authenticated user. Once
248        approved, the device can exchange the `device_code` for an access token.
249        Requires a valid user session the request must be authenticated as an end
250        user, not a machine client. The `user_code` must belong to a pending (not
251        expired, not already approved or denied) authorization associated with the
252        calling app.
253        If the requested scopes include a `thread`-scoped permission, you must supply
254        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
255
256        Args:
257            input: Request body.
258            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
259            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
260
261        Returns:
262            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
263        """
264        return self._http.request(
265            "/oauth/device/approve",
266            method="POST",
267            body=input,
268            response_type=DeviceAuthorizationStatusResponse,
269        )
270
271    def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
272        """
273        Inspect a pending device authorization
274        Returns the client name, requested scopes, and expiration for a pending
275        device authorization owned by the calling app. The caller must be an
276        authenticated user. This endpoint never approves the request.
277
278        Args:
279            code: User-facing device authorization code.
280
281        Returns:
282            Successful response
283        """
284        query: dict[str, object] = {}
285        query["code"] = code
286        return self._http.request(
287            "/oauth/device/authorization",
288            query=query,
289            response_type=DeviceAuthorizationDetailsResponse,
290        )
291
292    def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
293        """
294        Initiate a device authorization request
295        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
296        perform browser-based redirects. Returns a `device_code` (used by the device
297        to poll for a token) and a `user_code` (shown to the user to enter at the
298        `verification_uri`).
299        This endpoint requires a publishable API key; secret keys are rejected with
300        a 403. Third-party OAuth must be enabled on the app; if it is not, the
301        response returns `error: "third_party_oauth_not_enabled"` with a 403.
302        The endpoint is rate-limited to 10 requests per IP per minute. Excess
303        requests receive a 429 response. The returned codes expire after
304        `expires_in` seconds; once expired, a new authorization request must be
305        initiated.
306
307        Args:
308            input: Request body.
309            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
310            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
311
312        Returns:
313            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`.
314        """
315        return self._http.request(
316            "/oauth/device/authorize",
317            method="POST",
318            body=input,
319            response_type=DeviceAuthorizationResponse,
320        )
321
322    def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
323        """
324        Deny a device authorization request
325        Rejects the pending device authorization identified by `user_code`, preventing
326        the device from obtaining an access token. Once denied, the device will
327        receive an `access_denied` error on its next token poll.
328        Requires a valid user session. The `user_code` must belong to a pending
329        authorization associated with the calling app. Attempting to deny an already
330        approved, already denied, or expired authorization returns a 400.
331
332        Args:
333            input: Request body.
334            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
335
336        Returns:
337            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
338        """
339        return self._http.request(
340            "/oauth/device/deny",
341            method="POST",
342            body=input,
343            response_type=DeviceAuthorizationStatusResponse,
344        )
345
346
347class OauthResource:
348    def __init__(self, http: SyncHttpClient):
349        self._http = http
350        self.device = DeviceResource(http)
351
352    def scopes(self) -> OauthScopesResponse:
353        """
354        List available OAuth scopes
355        Returns the complete set of OAuth scopes that the platform supports.
356        Use this endpoint to discover which scopes are available before constructing
357        an authorization request or rendering a consent UI.
358        No authentication is required. The response is the same for all callers.
359
360        Returns:
361            Successful response
362        """
363        return self._http.request("/oauth/scopes", response_type=OauthScopesResponse)
364
365    def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
366        """
367        Exchange a grant for OAuth tokens
368        Issues an access token and a refresh token in exchange for a valid grant.
369        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
370        and `"urn:ietf:params:oauth:grant-type:device_code"`.
371        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
372        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
373        consuming it a second time returns `invalid_grant`.
374        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
375        refresh token on every call and returns a fresh pair of tokens.
376        For device-code grants, supply `device_code` and `client`. Poll this endpoint
377        after receiving `authorization_pending` until the user approves or the code
378        expires. Slow down polling if you receive `slow_down`.
379        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
380        the limit returns HTTP 429 with `"error": "too_many_requests"`.
381
382        Args:
383            input: Request body.
384            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
385            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
386            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
387            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
388            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
389            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
390            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
391
392        Returns:
393            Token pair issued for the authenticated user.
394        """
395        return self._http.request(
396            "/oauth/token",
397            method="POST",
398            body=input,
399            response_type=OAuthTokenResponse,
400        )
class DeviceApproveInput(typing.TypedDict): 
21class DeviceApproveInput(TypedDict, total=False):
22    "Approve a device authorization request"
23
24    thread: str | None
25    "Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission."
26    user_code: Required[str]
27    "User-facing verification code shown on the device. Identifies the pending authorization to approve."

Approve a device authorization request

thread: str | None

Thread ID (thr_...) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.

user_code: Required[str]

User-facing verification code shown on the device. Identifies the pending authorization to approve.

class DeviceAuthorizeInput(typing.TypedDict): 
30class DeviceAuthorizeInput(TypedDict, total=False):
31    "Initiate a device authorization request"
32
33    client: Required[str]
34    "OAuth client ID (`cli_...`) identifying the application requesting authorization."
35    scope: str | None
36    'Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.'

Initiate a device authorization request

client: Required[str]

OAuth client ID (cli_...) identifying the application requesting authorization.

scope: str | None

Space-separated list of OAuth scopes to request, e.g. "read write". Omit to request only the default scopes configured for the client.

class DeviceDenyInput(typing.TypedDict): 
39class DeviceDenyInput(TypedDict):
40    "Deny a device authorization request"
41
42    user_code: str
43    "User-facing verification code shown on the device. Identifies the pending authorization to deny."

Deny a device authorization request

user_code: str

User-facing verification code shown on the device. Identifies the pending authorization to deny.

class OauthTokenInput(typing.TypedDict): 
46class OauthTokenInput(TypedDict, total=False):
47    "Exchange a grant for OAuth tokens"
48
49    client: str | None
50    'OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.'
51    code: str | None
52    'Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.'
53    code_verifier: str | None
54    "PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise."
55    device_code: str | None
56    "Device code received from the device authorization endpoint. Required for device-code grants."
57    grant_type: Required[str]
58    'The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.'
59    redirect_uri: str | None
60    'Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.'
61    refresh_token: str | None
62    'Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.'

Exchange a grant for OAuth tokens

client: str | None

OAuth client ID identifying the application requesting tokens. Required for "authorization_code" and device-code grants.

code: str | None

Single-use authorization code issued by the authorization endpoint. Required for "authorization_code" grants.

code_verifier: str | None

PKCE code verifier corresponding to the code_challenge sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.

device_code: str | None

Device code received from the device authorization endpoint. Required for device-code grants.

grant_type: Required[str]

The OAuth 2.0 grant type. One of "authorization_code", "refresh_token", or "urn:ietf:params:oauth:grant-type:device_code".

redirect_uri: str | None

Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for "authorization_code" grants.

refresh_token: str | None

Refresh token received from a previous token response. Required for "refresh_token" grants. The token is rotated on each successful call.

class OauthScopesResponse(pydantic.main.BaseModel): 
65class OauthScopesResponse(BaseModel):
66    """
67    Successful response
68    """
69
70    scopes: dict[str, Any] = Field(
71        ...,
72        description='Map of scope name to its definition object. Each key is a scope string (e.g. `"threads:read"`) and each value describes the scope\'s purpose and requirements.',
73    )

Successful response

scopes: dict[str, typing.Any] = PydanticUndefined

Map of scope name to its definition object. Each key is a scope string (e.g. "threads:read") and each value describes the scope's purpose and requirements.

class AsyncDeviceResource: 
 76class AsyncDeviceResource:
 77    def __init__(self, http: HttpClient):
 78        self._http = http
 79
 80    async def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
 81        """
 82        Approve a device authorization request
 83        Grants the pending device authorization identified by `user_code`, completing
 84        the OAuth Device Authorization flow on behalf of the authenticated user. Once
 85        approved, the device can exchange the `device_code` for an access token.
 86        Requires a valid user session the request must be authenticated as an end
 87        user, not a machine client. The `user_code` must belong to a pending (not
 88        expired, not already approved or denied) authorization associated with the
 89        calling app.
 90        If the requested scopes include a `thread`-scoped permission, you must supply
 91        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
 92
 93        Args:
 94            input: Request body.
 95            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
 96            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
 97
 98        Returns:
 99            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
100        """
101        return await self._http.request(
102            "/oauth/device/approve",
103            method="POST",
104            body=input,
105            response_type=DeviceAuthorizationStatusResponse,
106        )
107
108    async def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
109        """
110        Inspect a pending device authorization
111        Returns the client name, requested scopes, and expiration for a pending
112        device authorization owned by the calling app. The caller must be an
113        authenticated user. This endpoint never approves the request.
114
115        Args:
116            code: User-facing device authorization code.
117
118        Returns:
119            Successful response
120        """
121        query: dict[str, object] = {}
122        query["code"] = code
123        return await self._http.request(
124            "/oauth/device/authorization",
125            query=query,
126            response_type=DeviceAuthorizationDetailsResponse,
127        )
128
129    async def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
130        """
131        Initiate a device authorization request
132        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
133        perform browser-based redirects. Returns a `device_code` (used by the device
134        to poll for a token) and a `user_code` (shown to the user to enter at the
135        `verification_uri`).
136        This endpoint requires a publishable API key; secret keys are rejected with
137        a 403. Third-party OAuth must be enabled on the app; if it is not, the
138        response returns `error: "third_party_oauth_not_enabled"` with a 403.
139        The endpoint is rate-limited to 10 requests per IP per minute. Excess
140        requests receive a 429 response. The returned codes expire after
141        `expires_in` seconds; once expired, a new authorization request must be
142        initiated.
143
144        Args:
145            input: Request body.
146            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
147            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
148
149        Returns:
150            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`.
151        """
152        return await self._http.request(
153            "/oauth/device/authorize",
154            method="POST",
155            body=input,
156            response_type=DeviceAuthorizationResponse,
157        )
158
159    async def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
160        """
161        Deny a device authorization request
162        Rejects the pending device authorization identified by `user_code`, preventing
163        the device from obtaining an access token. Once denied, the device will
164        receive an `access_denied` error on its next token poll.
165        Requires a valid user session. The `user_code` must belong to a pending
166        authorization associated with the calling app. Attempting to deny an already
167        approved, already denied, or expired authorization returns a 400.
168
169        Args:
170            input: Request body.
171            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
172
173        Returns:
174            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
175        """
176        return await self._http.request(
177            "/oauth/device/deny",
178            method="POST",
179            body=input,
180            response_type=DeviceAuthorizationStatusResponse,
181        )
AsyncDeviceResource(http: archastro.platform.runtime.http_client.HttpClient) 
77    def __init__(self, http: HttpClient):
78        self._http = http
async def approve( self, input: DeviceApproveInput) -> archastro.platform.types.device.DeviceAuthorizationStatusResponse: 
 80    async def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
 81        """
 82        Approve a device authorization request
 83        Grants the pending device authorization identified by `user_code`, completing
 84        the OAuth Device Authorization flow on behalf of the authenticated user. Once
 85        approved, the device can exchange the `device_code` for an access token.
 86        Requires a valid user session the request must be authenticated as an end
 87        user, not a machine client. The `user_code` must belong to a pending (not
 88        expired, not already approved or denied) authorization associated with the
 89        calling app.
 90        If the requested scopes include a `thread`-scoped permission, you must supply
 91        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
 92
 93        Args:
 94            input: Request body.
 95            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
 96            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
 97
 98        Returns:
 99            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
100        """
101        return await self._http.request(
102            "/oauth/device/approve",
103            method="POST",
104            body=input,
105            response_type=DeviceAuthorizationStatusResponse,
106        )

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".

Arguments:
  • input: Request body.
  • input.thread: Thread ID (thr_...) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
  • input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
Returns:

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

async def authorization( self, code: str) -> archastro.platform.types.device.DeviceAuthorizationDetailsResponse: 
108    async def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
109        """
110        Inspect a pending device authorization
111        Returns the client name, requested scopes, and expiration for a pending
112        device authorization owned by the calling app. The caller must be an
113        authenticated user. This endpoint never approves the request.
114
115        Args:
116            code: User-facing device authorization code.
117
118        Returns:
119            Successful response
120        """
121        query: dict[str, object] = {}
122        query["code"] = code
123        return await self._http.request(
124            "/oauth/device/authorization",
125            query=query,
126            response_type=DeviceAuthorizationDetailsResponse,
127        )

Inspect a pending device authorization Returns the client name, requested scopes, and expiration for a pending device authorization owned by the calling app. The caller must be an authenticated user. This endpoint never approves the request.

Arguments:
  • code: User-facing device authorization code.
Returns:

Successful response

async def authorize( self, input: DeviceAuthorizeInput) -> archastro.platform.types.device.DeviceAuthorizationResponse: 
129    async def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
130        """
131        Initiate a device authorization request
132        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
133        perform browser-based redirects. Returns a `device_code` (used by the device
134        to poll for a token) and a `user_code` (shown to the user to enter at the
135        `verification_uri`).
136        This endpoint requires a publishable API key; secret keys are rejected with
137        a 403. Third-party OAuth must be enabled on the app; if it is not, the
138        response returns `error: "third_party_oauth_not_enabled"` with a 403.
139        The endpoint is rate-limited to 10 requests per IP per minute. Excess
140        requests receive a 429 response. The returned codes expire after
141        `expires_in` seconds; once expired, a new authorization request must be
142        initiated.
143
144        Args:
145            input: Request body.
146            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
147            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
148
149        Returns:
150            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`.
151        """
152        return await self._http.request(
153            "/oauth/device/authorize",
154            method="POST",
155            body=input,
156            response_type=DeviceAuthorizationResponse,
157        )

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.

Arguments:
  • input: Request body.
  • input.client: OAuth client ID (cli_...) identifying the application requesting authorization.
  • input.scope: Space-separated list of OAuth scopes to request, e.g. "read write". Omit to request only the default scopes configured for the client.
Returns:

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.

async def deny( self, input: DeviceDenyInput) -> archastro.platform.types.device.DeviceAuthorizationStatusResponse: 
159    async def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
160        """
161        Deny a device authorization request
162        Rejects the pending device authorization identified by `user_code`, preventing
163        the device from obtaining an access token. Once denied, the device will
164        receive an `access_denied` error on its next token poll.
165        Requires a valid user session. The `user_code` must belong to a pending
166        authorization associated with the calling app. Attempting to deny an already
167        approved, already denied, or expired authorization returns a 400.
168
169        Args:
170            input: Request body.
171            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
172
173        Returns:
174            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
175        """
176        return await self._http.request(
177            "/oauth/device/deny",
178            method="POST",
179            body=input,
180            response_type=DeviceAuthorizationStatusResponse,
181        )

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.

Arguments:
  • input: Request body.
  • input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
Returns:

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

class AsyncOauthResource: 
184class AsyncOauthResource:
185    def __init__(self, http: HttpClient):
186        self._http = http
187        self.device = AsyncDeviceResource(http)
188
189    async def scopes(self) -> OauthScopesResponse:
190        """
191        List available OAuth scopes
192        Returns the complete set of OAuth scopes that the platform supports.
193        Use this endpoint to discover which scopes are available before constructing
194        an authorization request or rendering a consent UI.
195        No authentication is required. The response is the same for all callers.
196
197        Returns:
198            Successful response
199        """
200        return await self._http.request("/oauth/scopes", response_type=OauthScopesResponse)
201
202    async def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
203        """
204        Exchange a grant for OAuth tokens
205        Issues an access token and a refresh token in exchange for a valid grant.
206        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
207        and `"urn:ietf:params:oauth:grant-type:device_code"`.
208        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
209        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
210        consuming it a second time returns `invalid_grant`.
211        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
212        refresh token on every call and returns a fresh pair of tokens.
213        For device-code grants, supply `device_code` and `client`. Poll this endpoint
214        after receiving `authorization_pending` until the user approves or the code
215        expires. Slow down polling if you receive `slow_down`.
216        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
217        the limit returns HTTP 429 with `"error": "too_many_requests"`.
218
219        Args:
220            input: Request body.
221            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
222            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
223            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
224            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
225            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
226            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
227            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
228
229        Returns:
230            Token pair issued for the authenticated user.
231        """
232        return await self._http.request(
233            "/oauth/token",
234            method="POST",
235            body=input,
236            response_type=OAuthTokenResponse,
237        )
AsyncOauthResource(http: archastro.platform.runtime.http_client.HttpClient) 
185    def __init__(self, http: HttpClient):
186        self._http = http
187        self.device = AsyncDeviceResource(http)
device
async def scopes(self) -> OauthScopesResponse: 
189    async def scopes(self) -> OauthScopesResponse:
190        """
191        List available OAuth scopes
192        Returns the complete set of OAuth scopes that the platform supports.
193        Use this endpoint to discover which scopes are available before constructing
194        an authorization request or rendering a consent UI.
195        No authentication is required. The response is the same for all callers.
196
197        Returns:
198            Successful response
199        """
200        return await self._http.request("/oauth/scopes", response_type=OauthScopesResponse)

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.

Returns:

Successful response

async def token( self, input: OauthTokenInput) -> archastro.platform.types.oauth.OAuthTokenResponse: 
202    async def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
203        """
204        Exchange a grant for OAuth tokens
205        Issues an access token and a refresh token in exchange for a valid grant.
206        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
207        and `"urn:ietf:params:oauth:grant-type:device_code"`.
208        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
209        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
210        consuming it a second time returns `invalid_grant`.
211        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
212        refresh token on every call and returns a fresh pair of tokens.
213        For device-code grants, supply `device_code` and `client`. Poll this endpoint
214        after receiving `authorization_pending` until the user approves or the code
215        expires. Slow down polling if you receive `slow_down`.
216        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
217        the limit returns HTTP 429 with `"error": "too_many_requests"`.
218
219        Args:
220            input: Request body.
221            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
222            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
223            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
224            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
225            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
226            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
227            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
228
229        Returns:
230            Token pair issued for the authenticated user.
231        """
232        return await self._http.request(
233            "/oauth/token",
234            method="POST",
235            body=input,
236            response_type=OAuthTokenResponse,
237        )

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".

Arguments:
  • input: Request body.
  • input.client: OAuth client ID identifying the application requesting tokens. Required for "authorization_code" and device-code grants.
  • input.code: Single-use authorization code issued by the authorization endpoint. Required for "authorization_code" grants.
  • input.code_verifier: PKCE code verifier corresponding to the code_challenge sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
  • input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
  • input.grant_type: The OAuth 2.0 grant type. One of "authorization_code", "refresh_token", or "urn:ietf:params:oauth:grant-type:device_code".
  • input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for "authorization_code" grants.
  • input.refresh_token: Refresh token received from a previous token response. Required for "refresh_token" grants. The token is rotated on each successful call.
Returns:

Token pair issued for the authenticated user.

class DeviceResource: 
240class DeviceResource:
241    def __init__(self, http: SyncHttpClient):
242        self._http = http
243
244    def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
245        """
246        Approve a device authorization request
247        Grants the pending device authorization identified by `user_code`, completing
248        the OAuth Device Authorization flow on behalf of the authenticated user. Once
249        approved, the device can exchange the `device_code` for an access token.
250        Requires a valid user session the request must be authenticated as an end
251        user, not a machine client. The `user_code` must belong to a pending (not
252        expired, not already approved or denied) authorization associated with the
253        calling app.
254        If the requested scopes include a `thread`-scoped permission, you must supply
255        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
256
257        Args:
258            input: Request body.
259            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
260            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
261
262        Returns:
263            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
264        """
265        return self._http.request(
266            "/oauth/device/approve",
267            method="POST",
268            body=input,
269            response_type=DeviceAuthorizationStatusResponse,
270        )
271
272    def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
273        """
274        Inspect a pending device authorization
275        Returns the client name, requested scopes, and expiration for a pending
276        device authorization owned by the calling app. The caller must be an
277        authenticated user. This endpoint never approves the request.
278
279        Args:
280            code: User-facing device authorization code.
281
282        Returns:
283            Successful response
284        """
285        query: dict[str, object] = {}
286        query["code"] = code
287        return self._http.request(
288            "/oauth/device/authorization",
289            query=query,
290            response_type=DeviceAuthorizationDetailsResponse,
291        )
292
293    def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
294        """
295        Initiate a device authorization request
296        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
297        perform browser-based redirects. Returns a `device_code` (used by the device
298        to poll for a token) and a `user_code` (shown to the user to enter at the
299        `verification_uri`).
300        This endpoint requires a publishable API key; secret keys are rejected with
301        a 403. Third-party OAuth must be enabled on the app; if it is not, the
302        response returns `error: "third_party_oauth_not_enabled"` with a 403.
303        The endpoint is rate-limited to 10 requests per IP per minute. Excess
304        requests receive a 429 response. The returned codes expire after
305        `expires_in` seconds; once expired, a new authorization request must be
306        initiated.
307
308        Args:
309            input: Request body.
310            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
311            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
312
313        Returns:
314            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`.
315        """
316        return self._http.request(
317            "/oauth/device/authorize",
318            method="POST",
319            body=input,
320            response_type=DeviceAuthorizationResponse,
321        )
322
323    def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
324        """
325        Deny a device authorization request
326        Rejects the pending device authorization identified by `user_code`, preventing
327        the device from obtaining an access token. Once denied, the device will
328        receive an `access_denied` error on its next token poll.
329        Requires a valid user session. The `user_code` must belong to a pending
330        authorization associated with the calling app. Attempting to deny an already
331        approved, already denied, or expired authorization returns a 400.
332
333        Args:
334            input: Request body.
335            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
336
337        Returns:
338            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
339        """
340        return self._http.request(
341            "/oauth/device/deny",
342            method="POST",
343            body=input,
344            response_type=DeviceAuthorizationStatusResponse,
345        )
DeviceResource(http: archastro.platform.runtime.http_client.SyncHttpClient) 
241    def __init__(self, http: SyncHttpClient):
242        self._http = http
def approve( self, input: DeviceApproveInput) -> archastro.platform.types.device.DeviceAuthorizationStatusResponse: 
244    def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusResponse:
245        """
246        Approve a device authorization request
247        Grants the pending device authorization identified by `user_code`, completing
248        the OAuth Device Authorization flow on behalf of the authenticated user. Once
249        approved, the device can exchange the `device_code` for an access token.
250        Requires a valid user session the request must be authenticated as an end
251        user, not a machine client. The `user_code` must belong to a pending (not
252        expired, not already approved or denied) authorization associated with the
253        calling app.
254        If the requested scopes include a `thread`-scoped permission, you must supply
255        the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.
256
257        Args:
258            input: Request body.
259            input.thread: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
260            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
261
262        Returns:
263            Confirmation that the device authorization was approved. The `status` field will be `"approved"`.
264        """
265        return self._http.request(
266            "/oauth/device/approve",
267            method="POST",
268            body=input,
269            response_type=DeviceAuthorizationStatusResponse,
270        )

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".

Arguments:
  • input: Request body.
  • input.thread: Thread ID (thr_...) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
  • input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to approve.
Returns:

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

def authorization( self, code: str) -> archastro.platform.types.device.DeviceAuthorizationDetailsResponse: 
272    def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse:
273        """
274        Inspect a pending device authorization
275        Returns the client name, requested scopes, and expiration for a pending
276        device authorization owned by the calling app. The caller must be an
277        authenticated user. This endpoint never approves the request.
278
279        Args:
280            code: User-facing device authorization code.
281
282        Returns:
283            Successful response
284        """
285        query: dict[str, object] = {}
286        query["code"] = code
287        return self._http.request(
288            "/oauth/device/authorization",
289            query=query,
290            response_type=DeviceAuthorizationDetailsResponse,
291        )

Inspect a pending device authorization Returns the client name, requested scopes, and expiration for a pending device authorization owned by the calling app. The caller must be an authenticated user. This endpoint never approves the request.

Arguments:
  • code: User-facing device authorization code.
Returns:

Successful response

def authorize( self, input: DeviceAuthorizeInput) -> archastro.platform.types.device.DeviceAuthorizationResponse: 
293    def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse:
294        """
295        Initiate a device authorization request
296        Starts the OAuth 2.0 Device Authorization flow for a device that cannot
297        perform browser-based redirects. Returns a `device_code` (used by the device
298        to poll for a token) and a `user_code` (shown to the user to enter at the
299        `verification_uri`).
300        This endpoint requires a publishable API key; secret keys are rejected with
301        a 403. Third-party OAuth must be enabled on the app; if it is not, the
302        response returns `error: "third_party_oauth_not_enabled"` with a 403.
303        The endpoint is rate-limited to 10 requests per IP per minute. Excess
304        requests receive a 429 response. The returned codes expire after
305        `expires_in` seconds; once expired, a new authorization request must be
306        initiated.
307
308        Args:
309            input: Request body.
310            input.client: OAuth client ID (`cli_...`) identifying the application requesting authorization.
311            input.scope: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
312
313        Returns:
314            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`.
315        """
316        return self._http.request(
317            "/oauth/device/authorize",
318            method="POST",
319            body=input,
320            response_type=DeviceAuthorizationResponse,
321        )

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.

Arguments:
  • input: Request body.
  • input.client: OAuth client ID (cli_...) identifying the application requesting authorization.
  • input.scope: Space-separated list of OAuth scopes to request, e.g. "read write". Omit to request only the default scopes configured for the client.
Returns:

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.

def deny( self, input: DeviceDenyInput) -> archastro.platform.types.device.DeviceAuthorizationStatusResponse: 
323    def deny(self, input: DeviceDenyInput) -> DeviceAuthorizationStatusResponse:
324        """
325        Deny a device authorization request
326        Rejects the pending device authorization identified by `user_code`, preventing
327        the device from obtaining an access token. Once denied, the device will
328        receive an `access_denied` error on its next token poll.
329        Requires a valid user session. The `user_code` must belong to a pending
330        authorization associated with the calling app. Attempting to deny an already
331        approved, already denied, or expired authorization returns a 400.
332
333        Args:
334            input: Request body.
335            input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
336
337        Returns:
338            Confirmation that the device authorization was denied. The `status` field will be `"denied"`.
339        """
340        return self._http.request(
341            "/oauth/device/deny",
342            method="POST",
343            body=input,
344            response_type=DeviceAuthorizationStatusResponse,
345        )

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.

Arguments:
  • input: Request body.
  • input.user_code: User-facing verification code shown on the device. Identifies the pending authorization to deny.
Returns:

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

class OauthResource: 
348class OauthResource:
349    def __init__(self, http: SyncHttpClient):
350        self._http = http
351        self.device = DeviceResource(http)
352
353    def scopes(self) -> OauthScopesResponse:
354        """
355        List available OAuth scopes
356        Returns the complete set of OAuth scopes that the platform supports.
357        Use this endpoint to discover which scopes are available before constructing
358        an authorization request or rendering a consent UI.
359        No authentication is required. The response is the same for all callers.
360
361        Returns:
362            Successful response
363        """
364        return self._http.request("/oauth/scopes", response_type=OauthScopesResponse)
365
366    def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
367        """
368        Exchange a grant for OAuth tokens
369        Issues an access token and a refresh token in exchange for a valid grant.
370        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
371        and `"urn:ietf:params:oauth:grant-type:device_code"`.
372        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
373        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
374        consuming it a second time returns `invalid_grant`.
375        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
376        refresh token on every call and returns a fresh pair of tokens.
377        For device-code grants, supply `device_code` and `client`. Poll this endpoint
378        after receiving `authorization_pending` until the user approves or the code
379        expires. Slow down polling if you receive `slow_down`.
380        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
381        the limit returns HTTP 429 with `"error": "too_many_requests"`.
382
383        Args:
384            input: Request body.
385            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
386            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
387            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
388            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
389            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
390            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
391            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
392
393        Returns:
394            Token pair issued for the authenticated user.
395        """
396        return self._http.request(
397            "/oauth/token",
398            method="POST",
399            body=input,
400            response_type=OAuthTokenResponse,
401        )
OauthResource(http: archastro.platform.runtime.http_client.SyncHttpClient) 
349    def __init__(self, http: SyncHttpClient):
350        self._http = http
351        self.device = DeviceResource(http)
device
def scopes(self) -> OauthScopesResponse: 
353    def scopes(self) -> OauthScopesResponse:
354        """
355        List available OAuth scopes
356        Returns the complete set of OAuth scopes that the platform supports.
357        Use this endpoint to discover which scopes are available before constructing
358        an authorization request or rendering a consent UI.
359        No authentication is required. The response is the same for all callers.
360
361        Returns:
362            Successful response
363        """
364        return self._http.request("/oauth/scopes", response_type=OauthScopesResponse)

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.

Returns:

Successful response

def token( self, input: OauthTokenInput) -> archastro.platform.types.oauth.OAuthTokenResponse: 
366    def token(self, input: OauthTokenInput) -> OAuthTokenResponse:
367        """
368        Exchange a grant for OAuth tokens
369        Issues an access token and a refresh token in exchange for a valid grant.
370        Three grant types are supported: `"authorization_code"`, `"refresh_token"`,
371        and `"urn:ietf:params:oauth:grant-type:device_code"`.
372        For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and
373        optionally `code_verifier` for PKCE flows. Each authorization code is single-use;
374        consuming it a second time returns `invalid_grant`.
375        For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the
376        refresh token on every call and returns a fresh pair of tokens.
377        For device-code grants, supply `device_code` and `client`. Poll this endpoint
378        after receiving `authorization_pending` until the user approves or the code
379        expires. Slow down polling if you receive `slow_down`.
380        This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding
381        the limit returns HTTP 429 with `"error": "too_many_requests"`.
382
383        Args:
384            input: Request body.
385            input.client: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
386            input.code: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
387            input.code_verifier: PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
388            input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
389            input.grant_type: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
390            input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
391            input.refresh_token: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
392
393        Returns:
394            Token pair issued for the authenticated user.
395        """
396        return self._http.request(
397            "/oauth/token",
398            method="POST",
399            body=input,
400            response_type=OAuthTokenResponse,
401        )

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".

Arguments:
  • input: Request body.
  • input.client: OAuth client ID identifying the application requesting tokens. Required for "authorization_code" and device-code grants.
  • input.code: Single-use authorization code issued by the authorization endpoint. Required for "authorization_code" grants.
  • input.code_verifier: PKCE code verifier corresponding to the code_challenge sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
  • input.device_code: Device code received from the device authorization endpoint. Required for device-code grants.
  • input.grant_type: The OAuth 2.0 grant type. One of "authorization_code", "refresh_token", or "urn:ietf:params:oauth:grant-type:device_code".
  • input.redirect_uri: Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for "authorization_code" grants.
  • input.refresh_token: Refresh token received from a previous token response. Required for "refresh_token" grants. The token is rotated on each successful call.
Returns:

Token pair issued for the authenticated user.