> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a ChatGPT plan device sign-in

> Reads one of the caller's ChatGPT plan device sign-ins: pending until they sign in, then complete with the ChatGPT plan connection it stored.

Use this tool when you need to:
- Poll, every interval seconds, whether the caller finished the ChatGPT sign-in createChatgptPlanDeviceAuth started
- Get the ChatGPT plan connection a finished sign-in added or reconnected

Examples:
- GET /connections/chatgpt-plan/device-auths/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21

Hints:
- deviceAuthID is the id createChatgptPlanDeviceAuth returned; the schema answers 422 for a value that is not a uuid, and one that is not a canonical lowercase uuid is 404 device_auth_not_found.
- Answers status pending while ChatGPT has not seen the caller sign in (its poll answers 403 or 404), or status complete with connection, the ChatGPT plan connection stored as the start's mode named: a new one under its name (the Codex default when the caller has none), or the reconnected one, its id, name, tasks, profiles and defaults kept and its reauth cleared.
- The first read after the caller signs in stores the plan; every read after that answers with the same connection, read afresh, until that connection is disconnected, which deletes the sign-in (404 device_auth_not_found from then on).
- Use createChatgptPlanDeviceAuth instead to start a new sign-in, as after a 502 or a 404.
- Any signed-in user may call it for a sign-in they started, an agent host's grant included (the Aether CLI in the agent's box calls it for its owner); through a platform API key pinned to an org where the caller is a viewer or billing member it is refused with 403 org_role_insufficient.
- Refused with 404 device_auth_not_found for a sign-in the caller did not start, 409 connection_name_taken when the caller uses the name for another ChatGPT plan by the time it completes (the start does not check it), 409 connection_account_held when the ChatGPT account is already another of the caller's connections (the message names it: reconnect that one), and 502 when ChatGPT fails the sign-in or it expired: any other poll answer, or a failed code exchange or token parse.



## OpenAPI

````yaml api-reference/openapi.json GET /connections/chatgpt-plan/device-auths/{deviceAuthID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /connections/chatgpt-plan/device-auths/{deviceAuthID}:
    get:
      tags:
        - connections
      summary: Read a ChatGPT plan device sign-in
      description: >-
        Reads one of the caller's ChatGPT plan device sign-ins: pending until
        they sign in, then complete with the ChatGPT plan connection it stored.


        Use this tool when you need to:

        - Poll, every interval seconds, whether the caller finished the ChatGPT
        sign-in createChatgptPlanDeviceAuth started

        - Get the ChatGPT plan connection a finished sign-in added or
        reconnected


        Examples:

        - GET
        /connections/chatgpt-plan/device-auths/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21


        Hints:

        - deviceAuthID is the id createChatgptPlanDeviceAuth returned; the
        schema answers 422 for a value that is not a uuid, and one that is not a
        canonical lowercase uuid is 404 device_auth_not_found.

        - Answers status pending while ChatGPT has not seen the caller sign in
        (its poll answers 403 or 404), or status complete with connection, the
        ChatGPT plan connection stored as the start's mode named: a new one
        under its name (the Codex default when the caller has none), or the
        reconnected one, its id, name, tasks, profiles and defaults kept and its
        reauth cleared.

        - The first read after the caller signs in stores the plan; every read
        after that answers with the same connection, read afresh, until that
        connection is disconnected, which deletes the sign-in (404
        device_auth_not_found from then on).

        - Use createChatgptPlanDeviceAuth instead to start a new sign-in, as
        after a 502 or a 404.

        - Any signed-in user may call it for a sign-in they started, an agent
        host's grant included (the Aether CLI in the agent's box calls it for
        its owner); through a platform API key pinned to an org where the caller
        is a viewer or billing member it is refused with 403
        org_role_insufficient.

        - Refused with 404 device_auth_not_found for a sign-in the caller did
        not start, 409 connection_name_taken when the caller uses the name for
        another ChatGPT plan by the time it completes (the start does not check
        it), 409 connection_account_held when the ChatGPT account is already
        another of the caller's connections (the message names it: reconnect
        that one), and 502 when ChatGPT fails the sign-in or it expired: any
        other poll answer, or a failed code exchange or token parse.
      operationId: getChatgptPlanDeviceAuth
      parameters:
        - description: The device sign-in's id.
          in: path
          name: deviceAuthID
          required: true
          schema:
            description: The device sign-in's id.
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatgptPlanDeviceAuthStatus'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Internal Server Error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Bad Gateway
components:
  schemas:
    ChatgptPlanDeviceAuthStatus:
      description: >-
        A device sign-in still waiting for you to sign in (pending), or the
        ChatGPT plan connection it stored once you did (complete).
      discriminator:
        mapping:
          complete: '#/components/schemas/ChatgptPlanDeviceAuthComplete'
          pending: '#/components/schemas/ChatgptPlanDeviceAuthPending'
        propertyName: status
      oneOf:
        - $ref: '#/components/schemas/ChatgptPlanDeviceAuthPending'
        - $ref: '#/components/schemas/ChatgptPlanDeviceAuthComplete'
    ConnectionsErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - aether_inference_unavailable
            - aether_inference_unserved
            - agent_credential_unreadable
            - agent_host_account_deleting
            - agent_host_command_not_found
            - agent_host_creation_disabled
            - agent_host_exists
            - agent_host_illegal_transition
            - agent_host_not_allowlisted
            - agent_host_not_found
            - agent_host_other_provider_app
            - agent_host_project_not_eligible
            - agent_host_provisioning_failed
            - agent_host_state_changed
            - agent_host_wake_failed
            - agent_line_unavailable
            - bad_gateway
            - bad_request
            - cli_upgrade_required
            - client_outdated
            - conflict
            - connection_account_held
            - connection_agent_only
            - connection_harness_mismatch
            - connection_is_default
            - connection_name_taken
            - connection_not_found
            - connection_option_mismatch
            - connection_runs_agent
            - connection_runs_profiles
            - device_auth_not_found
            - fallback_is_own_connection
            - forbidden
            - gateway_timeout
            - gone
            - internal_error
            - line_exists
            - line_not_found
            - line_not_imessage
            - method_not_allowed
            - no_default_connection
            - not_acceptable
            - not_found
            - not_implemented
            - payment_required
            - precondition_failed
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - unauthenticated
            - unsupported_media_type
            - validation_failed
            - whatsapp_not_enabled
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ChatgptPlanDeviceAuthComplete:
      additionalProperties: false
      properties:
        connection:
          $ref: '#/components/schemas/ChatgptPlanConnection'
        status:
          enum:
            - complete
          type: string
      required:
        - status
        - connection
      type: object
    ChatgptPlanDeviceAuthPending:
      additionalProperties: false
      properties:
        status:
          enum:
            - pending
          type: string
      required:
        - status
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ChatgptPlanConnection:
      additionalProperties: false
      description: A ChatGPT plan's tokens.
      properties:
        email:
          description: The ChatGPT account's email, when its token names one.
          minLength: 1
          type: string
        id:
          format: uuid
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - chatgpt_plan
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    ConnectionCreditsLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - credits
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionModelLimit:
      additionalProperties: false
      properties:
        model:
          minLength: 1
          type: string
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - model
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
        - model
      type: object
    ConnectionSessionLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - session
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionUsageLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - usage
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionWeeklyLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - weekly
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionProfile:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
        name:
          minLength: 1
          type: string
        org:
          description: The name of the organization the profile belongs to.
          minLength: 1
          type: string
      required:
        - id
        - name
        - org
      type: object
    ConnectionReauth:
      additionalProperties: false
      properties:
        reason:
          description: Why the stored credential failed, as the vendor said.
          minLength: 1
          type: string
      required:
        - reason
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.