Archastro Oauth API

openapi: 3.0.0
info:
  description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
  title: ArchAstro Platform Activity Feed Oauth API
  version: v1
tags:
- name: Oauth
paths:
  /oauth/device/approve:
    post:
      description: '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"`.'
      operationId: post_oauth_device_approve
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                thread: string
                user_code: string
              properties:
                thread:
                  description: Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
                  example: string
                  type: string
                user_code:
                  description: User-facing verification code shown on the device. Identifies the pending authorization to approve.
                  example: string
                  type: string
              required:
              - user_code
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationStatusResponse'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      summary: Approve a device authorization request
      tags:
      - Oauth
  /oauth/device/authorize:
    post:
      description: '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.'
      operationId: post_oauth_device_authorize
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                client: string
                scope: string
              properties:
                client:
                  description: OAuth client ID (`cli_...`) identifying the application requesting authorization.
                  example: string
                  type: string
                scope:
                  description: Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.
                  example: string
                  type: string
              required:
              - client
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
          description: Successful response
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '429':
          description: Rate limited
      summary: Initiate a device authorization request
      tags:
      - Oauth
  /oauth/device/deny:
    post:
      description: '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.'
      operationId: post_oauth_device_deny
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                user_code: string
              properties:
                user_code:
                  description: User-facing verification code shown on the device. Identifies the pending authorization to deny.
                  example: string
                  type: string
              required:
              - user_code
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationStatusResponse'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      summary: Deny a device authorization request
      tags:
      - Oauth
  /oauth/scopes:
    get:
      description: '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.'
      operationId: get_oauth_scopes
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                description: An object containing all available OAuth scope definitions.
                example:
                  scopes: {}
                properties:
                  scopes:
                    description: Map of scope name to its definition object. Each key is a scope string (e.g. `"thread:read"`) and each value describes the scope's purpose and requirements.
                    example: {}
                    type: object
                required:
                - scopes
                type: object
          description: Successful response
      summary: List available OAuth scopes
      tags:
      - Oauth
  /oauth/token:
    post:
      description: '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"`.'
      operationId: post_oauth_token
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                client: string
                code: string
                code_verifier: string
                device_code: string
                grant_type: string
                redirect_uri: https://example.com
                refresh_token: string
              properties:
                client:
                  description: OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
                  example: string
                  type: string
                code:
                  description: Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
                  example: string
                  type: string
                code_verifier:
                  description: 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.
                  example: string
                  type: string
                device_code:
                  description: Device code received from the device authorization endpoint. Required for device-code grants.
                  example: string
                  type: string
                grant_type:
                  description: The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
                  example: string
                  type: string
                redirect_uri:
                  description: 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.
                  example: https://example.com
                  type: string
                refresh_token:
                  description: Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.
                  example: string
                  type: string
              required:
              - grant_type
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Rate limited
      summary: Exchange a grant for OAuth tokens
      tags:
      - Oauth
components:
  schemas:
    DeviceAuthorizationResponse:
      description: The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication.
      example:
        device_code: string
        expires_in: 1800
        interval: 5
        user_code: WDJB-MJHT
        verification_uri: https://example.com
        verification_uri_complete: string
      properties:
        device_code:
          description: Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.
          example: string
          type: string
        expires_in:
          description: Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow.
          example: 1800
          type: integer
        interval:
          description: Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a `slow_down` error.
          example: 5
          type: integer
        user_code:
          description: Short alphanumeric code the user must enter at `verification_uri` to authorize the device.
          example: WDJB-MJHT
          type: string
        verification_uri:
          description: URL the user visits to enter the `user_code` and approve the authorization request.
          example: https://example.com
          type: string
        verification_uri_complete:
          description: Full verification URL with the `user_code` pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry.
          example: string
          type: string
      required:
      - device_code
      - expires_in
      - interval
      - user_code
      - verification_uri
      - verification_uri_complete
      type: object
    User:
      description: A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.
      example:
        alias: jdoe
        app: dap_0aBcDeFgHiJkLmNoPqRsTu
        app_name: Example Name
        email: user@example.com
        id: usr_0aBcDeFgHiJkLmNoPqRsTu
        is_system_user: true
        metadata:
          key: value
        name: Example Name
        org: org_0aBcDeFgHiJkLmNoPqRsTu
        org_name: Example Name
        org_role: member
        sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
        sandbox_name: Example Name
      properties:
        alias:
          description: Short handle or alias for the user. `null` if not set.
          example: jdoe
          type: string
        app:
          description: ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
          example: dap_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        app_name:
          description: Display name of the user's app. `null` when the app association was not preloaded by the caller.
          example: Example Name
          type: string
        email:
          description: Email address of the user.
          example: user@example.com
          type: string
        id:
          description: User ID (`usr_...`).
          example: usr_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        is_system_user:
          description: '`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.'
          example: true
          type: boolean
        metadata:
          description: Arbitrary key-value metadata attached to the user. Defaults to an empty object.
          example:
            key: value
          type: object
        name:
          description: Full display name of the user. `null` if the user has not set a name.
          example: Example Name
          type: string
        org:
          description: ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
          example: org_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        org_name:
          description: Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
          example: Example Name
          type: string
        org_role:
          description: Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
          example: member
          type: string
        sandbox:
          description: ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
          example: dsb_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        sandbox_name:
          description: Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.
          example: Example Name
          type: string
      required:
      - id
      type: object
    DeviceAuthorizationStatusResponse:
      description: The result of a completed OAuth 2.0 Device Authorization flow, indicating whether the user approved or denied the device's access request.
      example:
        status: approved
      properties:
        status:
          description: Outcome of the device authorization request. One of `"approved"` (the user granted access) or `"denied"` (the user rejected or cancelled the request).
          example: approved
          type: string
      required:
      - status
      type: object
    OAuthTokenResponse:
      description: A successful OAuth 2.0 token response. Issued by the token endpoint after a completed authorization or device-flow grant.
      example:
        access_token: string
        expires_in: 3600
        refresh_token: string
        scope: read write
        token_type: Bearer
        user:
          alias: jdoe
          app: dap_0aBcDeFgHiJkLmNoPqRsTu
          app_name: Example Name
          email: user@example.com
          id: usr_0aBcDeFgHiJkLmNoPqRsTu
          is_system_user: true
          metadata:
            key: value
          name: Example Name
          org: org_0aBcDeFgHiJkLmNoPqRsTu
          org_name: Example Name
          org_role: member
          sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
          sandbox_name: Example Name
      properties:
        access_token:
          description: 'Bearer token used to authenticate API requests. Include this value in the `Authorization: Bearer <token>` header.'
          example: string
          type: string
          x-sdk: access_token
        expires_in:
          description: Number of seconds until the access token expires.
          example: 3600
          type: integer
          x-sdk: token_expiry
        refresh_token:
          description: Token that can be exchanged for a new access token once the current one expires. `null` if the grant type does not issue refresh tokens.
          example: string
          type: string
          x-sdk: refresh_token
        scope:
          description: Space-separated list of scopes granted to the access token. `null` if scope was not included in the grant request.
          example: read write
          type: string
        token_type:
          description: Token type. Always `"Bearer"`.
          example: Bearer
          type: string
        user:
          $ref: '#/components/schemas/User'
          description: The authenticated user associated with this token. `null` when the token is not tied to a specific user (e.g. client-credentials grants).
      required:
      - access_token
      - expires_in
      - token_type
      type: object
x-archastro-docs-scope: external
x-auth-schemes:
  bearer:
    description: User JWT in Authorization header
    scheme: bearer
    type: http
  device_flow:
    description: Third-party device flow token — requires per-action opt-in
    scheme: bearer
    type: http
    x-token-use: third_party
  publishable_key:
    description: Publishable API key — identifies the app
    in: header
    name: x-archastro-api-key
    prefix: pk_
    type: api_key
  secret_key:
    description: Secret API key — full admin access, no user JWT required
    in: header
    name: x-archastro-api-key
    prefix: sk_
    type: api_key
x-channel-auth:
- bearer
x-channels:
- description: 'Channel for real-time chat messaging.


    Supports team-scoped and user-scoped threads with keyed, transient, and direct

    thread access patterns.'
  joins:
  - description: Join a team-scoped thread by ID
    name: join_team_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        team_id: string
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
        thread_id:
          example: string
          type: string
      required:
      - team_id
      - thread_id
      type: object
    pattern: api:chat:team:{team_id}:thread:{thread_id}
    returns:
      type: object
  - description: Join a team-scoped transient (ephemeral) thread
    name: join_team_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:transient:{key}
    returns:
      type: object
  - description: Join a user-scoped thread by ID
    name: join_user_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        thread_id:
          example: string
          type: string
      required:
      - thread_id
      type: object
    pattern: api:chat:user:thread:{thread_id}
    returns:
      type: object
  - description: Join a user-scoped transient (ephemeral) thread
    name: join_user_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:transient:{key}
    returns:
      type: object
  - description: Join or create a team-scoped keyed thread
    name: join_team_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:key:{key}
    returns:
      type: object
  - description: Join or create a user-scoped keyed thread
    name: join_user_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:key:{key}
    returns:
      type: object
  messages:
  - description: Add an emoji reaction to a message
    event: api:chat:add_reaction
    params:
      example:
        emoji: string
        message_id: string
      properties:
        emoji:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - emoji
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Delete a message
    event: api:chat:delete_message
    params:
      example:
        message_id: string
      properties:
        message_id:
          example: string
          type: string
      required:
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Edit an existing message's content
    event: api:chat:edit_message
    params:
      example:
        content: string
        message_id: string
      properties:
        content:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - content
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Fork a sub-thread from an existing message
    event: api:chat:fork_thread
    params:
      example:
        message_id: string
        title: Example Title
      properties:
        message_id:
          example: string
          type: string
        title:
          example: Example Title
          type: string
      required:
      - message_id
      type: object
    returns:
      description: Response returned after forking a chat thread. Contains the new thread, its initial chat-room snapshot, and the owning team when applicable.
      example:
        chat_model:
          after_cursor: string
          agent:
            acl:
              add:
              - actions:
                - read
                - write
                principal: string
                principal_type: user
              grants:
              - actions:
                - read
                - write
                principal: string
                principal_type: user
              remove:
              - principal: string
                principal_type: user
            app: dap_0aBcDeFgHiJkLmNoPqRsTu
            created_at: '2024-01-01T00:00:00Z'
            default_model: claude-3-7-sonnet-latest
            email: user@example.com
            id: agi_0aBcDeFgHiJkLmNoPqRsTu
            identity: You are a helpful assistant that answers questions about ArchAstro products.
            last_applied_template_config: cfg_0aBcDeFgHiJkLmNoPqRsTu
            lookup_key: string
            metadata:
              key: value
            name: Example Name
            org: org_0aBcDeFgHiJkLmNoPqRsTu
            org_name: Example Name
            originator: deploy-pipeline
            phone_number: '+15555550123'
            sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
            source_solution:
              solution:
                category_keys:
                - string
                created_at: '2024-01-01T00:00:00Z'
                description: An example description.
                id: id_0aBcDeFgHiJkLmNoPqRsTu
                kind: Solution
                latest_solution: id_0aBcDeFgHiJkLmNoPqRsTu
                latest_version: 1.0.0
                lookup_key: string
                metadata:
                  key: value
                name: Example Name
                org: org_0aBcDeFgHiJkLmNoPqRsTu
                org_logo:
                  file: fil_0aBcDeFgHiJkLmNoPqRsTu
                  height: 600
                  media: med_0aBcDeFgHiJkLmNoPqRsTu
                  mime_type: application/json
                  refresh_url: https://example.com
                  url: https://example.com
                  width: 800
                org_name: Example Name
                org_slug: example-slug
                owners:
                - string
                readme_url: https://example.com
                solution_id: 01234567-89ab-cdef-0123-456789abcdef
                solution_version: 1.2.0
                tag_keys:
                - string
                template_kind: AgentTemplate
                templates:
                - description: An example description.
                  display_name: Example Name
                  id: id_0aBcDeFgHiJkLmNoPqRsTu
                  kind: AgentTemplate
                  lookup_key: string
                  name: Example Name
                  readme_url: https://example.com
                  virtual_path: string
                updated_at: '2024-01-01T00:00:00Z'
                upgrade_available: true
                virtual_path: string
              template:
                created_at: '2024-01-01T00:00:00Z'
                description: An example description.
                display_name: Example Name
                id: id_0aBcDeFgHiJkLmNoPqRsTu
                kind: agent_tool_template
                lookup_key: string
                name: Example Name
                updated_at: '2024-01-01T00:00:00Z'
                virtual_path: string
            team: tem_0aBcDeFgHiJkLmNoPqRsTu
            updated_at: '2024-01-01T00:00:00Z'
            user: usr_0aBcDeFgHiJkLmNoPqRsTu
          before_cursor: string
          is_transient: true
          members:
          - agent:
              acl:
                add:
                - actions:
                  - read
                  - write
                  principal: string
                  principal_type: user
                grants:
                - actions:
                  - read
                  - write
                  principal: string
                  principal_type: user
                remove:
                - principal: string
                  principal_type: user
              app: dap_0aBcDeFgHiJkLmNoPqRsTu
              created_at: '2024-01-01T00:00:00Z'
              default_model: claude-3-7-sonnet-latest
              email: user@example.com
              id: agi_0aBcDeFgHiJkLmNoPqRsTu
              identity: You are a helpful assistant that answers questions about ArchAstro products.
              last_applied_template_config: cfg_0aBcDeFgHiJkLmNoPqRsTu
              lookup_key: string
              metadata:
                key: value
              name: Example Name
              org: org_0aBcDeFgHiJkLmNoPqRsTu
              org_name: Example Name
              originator: deploy-pipeline
              phone_number: '+15555550123'
              sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
              source_solution:
                solution:
                  category_keys:
                  - string
                  created_at: '2024-01-01T00:00:00Z'
                  description: An example description.
                  id: id_0aBcDeFgHiJkLmNoPqRsTu
                  kind: Solution
                  latest_solution: id_0aBcDeFgHiJkLmNoPqRsTu
                  latest_version: 1.0.0
                  lookup_key: string
                  metadata:
                    key: value
                  name: Example Name
                  org: org_0aBcDeFgHiJkLmNoPqRsTu
                  org_logo:
                    file: fil_0aBcDeFgHiJkLmNoPqRsTu
                    height: 600
                    media: med_0aBcDeFgHiJkLmNoPqRsTu
                    mime_type: application/json
                    refresh_url: https://example.com
                    url: https://example.com
                    width: 800
                  org_name: Example Name
                  org_slug: example-slug
                  owners:
                  - string
                  readme_url: https://example.com
                  solution_id: 01234567-89ab-cdef-0123-456789abcdef
                  solution_version: 1.2.0
                  tag_keys:
                  - string
                  template_kind: AgentTemplate
                  templates:
                  - description: An example description.
                    display_name: Example Name
            

# --- truncated at 32 KB (1001 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-oauth-api-openapi.yml