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

# Post Consent Poll

> Poll for the customer's decision per RFC 8628 §3.5.

HTTP 200 + RFC 6749 §5.1 success body when the agent token is
minted; HTTP 400 + RFC 6749 §5.2 error body for every other state:

  authorization_pending  customer hasn't decided yet
  access_denied          customer denied
  expired_token          consent code expired before claim
  invalid_grant          unknown / malformed device_code
  already_claimed        agent already polled successfully (Stella ext)

Stock OAuth client libraries that read `access_token` on 200 and
`error` on 4xx work out of the box. The success body adds Stella
extensions `agent_name` and `budget_cents` so the agent doesn't
need a second call to learn the consent shape (RFC 6749 §5.1
explicitly allows extension parameters).



## OpenAPI

````yaml /api-reference/openapi.json post /api/agent/consent/poll
openapi: 3.1.0
info:
  title: Agentic Commerce API
  description: |2-

        Agentic Commerce API - E-commerce Backend

        ## APIs

        ### Dashboard API (`/api/dashboard`)
        Authenticated endpoints for merchant management:
        - Products, Variants, Options
        - Inventory management
        - Orders and fulfillment
        - Customers
        - Collections

        ### Storefront API (`/api/storefront`)
        Public endpoints for client websites:
        - Product catalog
        - Collections
        - Cart management
        - Checkout

        ### Sync API (`/api/sync`)
        Integration endpoints for zunkiree-search:
        - Product sync
        - Availability checks
        - Order creation from AI widget
        
  version: 1.0.0
servers: []
security: []
paths:
  /api/agent/consent/poll:
    post:
      tags:
        - Agent
        - Agent Consent
      summary: Post Consent Poll
      description: |-
        Poll for the customer's decision per RFC 8628 §3.5.

        HTTP 200 + RFC 6749 §5.1 success body when the agent token is
        minted; HTTP 400 + RFC 6749 §5.2 error body for every other state:

          authorization_pending  customer hasn't decided yet
          access_denied          customer denied
          expired_token          consent code expired before claim
          invalid_grant          unknown / malformed device_code
          already_claimed        agent already polled successfully (Stella ext)

        Stock OAuth client libraries that read `access_token` on 200 and
        `error` on 4xx work out of the box. The success body adds Stella
        extensions `agent_name` and `budget_cents` so the agent doesn't
        need a second call to learn the consent shape (RFC 6749 §5.1
        explicitly allows extension parameters).
      operationId: post_consent_poll_api_agent_consent_poll_post
      parameters:
        - name: X-Site-ID
          in: header
          required: true
          schema:
            type: string
            title: X-Site-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentConsentPollBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConsentPollSuccessResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConsentPollErrorResponse'
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentConsentPollBody:
      properties:
        device_code:
          type: string
          maxLength: 200
          minLength: 8
          title: Device Code
      type: object
      required:
        - device_code
      title: AgentConsentPollBody
      description: 'Agent → Stella: poll for consent decision.'
    AgentConsentPollSuccessResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: Bearer
        expires_in:
          type: integer
          title: Expires In
          description: Seconds remaining on the agt_ token's lifetime.
        scope:
          type: string
          title: Scope
          description: Space-separated list of approved scopes per RFC 6749 §3.3.
        agent_name:
          type: string
          title: Agent Name
        budget_cents:
          type: integer
          title: Budget Cents
      type: object
      required:
        - access_token
        - expires_in
        - scope
        - agent_name
        - budget_cents
      title: AgentConsentPollSuccessResponse
      description: |-
        Stella → agent: HTTP 200 success body per RFC 6749 §5.1.

        `scope` is space-separated (NOT a JSON array) per spec. `expires_in`
        is relative seconds (NOT a timestamp). Stella-specific extension
        fields `agent_name` and `budget_cents` carry the consent shape so
        the agent doesn't need a second call.
    AgentConsentPollErrorResponse:
      properties:
        error:
          type: string
          title: Error
        error_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Description
      type: object
      required:
        - error
      title: AgentConsentPollErrorResponse
      description: |-
        Stella → agent: HTTP 400 error body per RFC 6749 §5.2.

        `error` values used:

          * `authorization_pending` (RFC 8628 §3.5)
          * `access_denied` (RFC 8628 §3.5)
          * `expired_token` (RFC 8628 §3.5)
          * `invalid_grant` (RFC 6749 §5.2)
          * `slow_down` (RFC 8628 §3.5; reserved, not currently emitted)
          * `already_claimed` (Stella extension; RFC 6749 §5.2 explicitly
            permits extension error codes for OAuth profiles)
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````