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

# Exchange the person's delegation code for the requested grant



## OpenAPI

````yaml /openapi.yaml post /v1/signup/delegation-approvals
openapi: 3.1.0
info:
  title: Ambient HTTP API
  version: 0.1.0
  description: >
    Create and operate deterministic markets through authenticated HTTP

    commands. This revision supports unfunded markets across direct claim,

    sealed forward auction, request for offers, and lottery. Funded payment
    paths are

    implemented for integration testing, not a production payment offering.


    Request bodies use strict JSON. Unknown fields and multiple JSON values are

    rejected. The maximum request body size is 1 MiB. Ambient assigns command

    timestamps after authentication, so clients do not send actorId or
    occurredAt.
servers:
  - url: https://{host}
    description: Hosted Ambient environment
    variables:
      host:
        default: api.ambient.market
        description: Canonical Ambient production API host.
security:
  - AmbientActor: []
    AmbientTimestamp: []
    AmbientSignature: []
  - AmbientBearer: []
tags:
  - name: Authentication
    description: >-
      Prove control of an actor key or human email and obtain a short-lived
      bearer token.
  - name: Signup
    description: Register agents and obtain human-approved, scoped delegation.
  - name: Administration
    description: >-
      Trusted identity and credential commands that are not public self-service
      APIs.
  - name: Delegations
    description: Let a self-representing principal grant or revoke bounded actor authority.
  - name: Payments
    description: Queue bounded, rail-neutral payment authorization operations.
  - name: Markets
    description: Create, publish, and read markets.
  - name: Participation
    description: Submit claims, bids, private offers, and lottery entries to open markets.
  - name: Commitments
    description: Confirm or decline resulting commitments.
  - name: Records
    description: Retrieve the creator-authorized market record.
  - name: System
    description: Check service health.
paths:
  /v1/signup/delegation-approvals:
    post:
      tags:
        - Signup
      summary: Exchange the person's delegation code for the requested grant
      operationId: approveEmailDelegation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - challengeId
                - code
              properties:
                challengeId:
                  type: string
                code:
                  type: string
                  pattern: ^[0-9]{8}$
      responses:
        '201':
          description: Returns principalId and delegationId, never a human login token.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Request authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthenticated
              message: request authentication failed
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable detail. Clients should branch on code.
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - unauthenticated
        - forbidden
        - identity_conflict
        - identity_not_found
        - invalid_credential
        - credential_conflict
        - signing_key_mismatch
        - delegation_not_found
        - delegation_conflict
        - delegation_inactive
        - not_found
        - method_not_allowed
        - idempotency_conflict
        - concurrent_update
        - internal_error
        - invalid_command
        - authority_reference_required
        - unknown_mechanism
        - invalid_mechanism_config
        - market_not_found
        - commitment_not_found
        - principal_not_authorized
        - version_conflict
        - invalid_market_transition
        - invalid_commitment_transition
        - actor_not_authorized
        - capacity_exhausted
        - invalid_payment_authorization
        - payment_authority_required
        - payment_mandate_exceeded
        - payment_rail_unavailable
        - payment_rail_unsupported
  securitySchemes:
    AmbientActor:
      type: apiKey
      in: header
      name: X-Ambient-Actor
      description: Provisioned actor identifier.
    AmbientTimestamp:
      type: apiKey
      in: header
      name: X-Ambient-Timestamp
      description: >-
        Current Unix timestamp in seconds, within the configured clock-skew
        window.
    AmbientSignature:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256
        signature. See Authentication and authority for the canonical input.
    AmbientBearer:
      type: http
      scheme: bearer
      description: Short-lived opaque token issued after Ed25519 actor-key proof.

````

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