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