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

# Start a wallet session

> Exchanges the single-use identity credential presented in the `Authorization: Bearer` header for a wallet session belonging to the customer it identifies. Once the exchange accepts the credential it is spent, whether or not the rest of the exchange succeeds. Customers who have not verified an email address have no wallet and are refused. The Endstate wallet frame calls this endpoint; your own code does not.



## OpenAPI

````yaml /openapi.json post /v1/wallet/sessions
openapi: 3.1.0
info:
  title: Endstate API
  version: 0.1.0
  description: Endstate developer API for chip verification and ownership workflows.
servers:
  - url: https://api2.endstate.io
    description: Production
  - url: https://api-staging.endstate.io
    description: Staging
security: []
paths:
  /v1/wallet/sessions:
    post:
      tags:
        - Wallet
      summary: Start a wallet session
      description: >-
        Exchanges the single-use identity credential presented in the
        `Authorization: Bearer` header for a wallet session belonging to the
        customer it identifies. Once the exchange accepts the credential it is
        spent, whether or not the rest of the exchange succeeds. Customers who
        have not verified an email address have no wallet and are refused. The
        Endstate wallet frame calls this endpoint; your own code does not.
      operationId: createWalletSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletSessionRequest'
            example:
              publishable_key: end_pk_live_0123456789abcdef0123456789abcdef
      responses:
        '201':
          description: The session was started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWalletSessionResponse'
              example:
                token: eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...
                session_token: end_wsess_AbCd_example_token
                expires_at: 1755640000
                chain_id: 8453
        '400':
          description: >-
            The request was malformed or failed validation.


            | Error code | When |

            | --- | --- |

            | `validation.failed` | The request failed schema validation. See
            `error.details` for per-field issues. |
          x-error-codes:
            - validation.failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation.failed:
                  summary: >-
                    The request failed schema validation. See `error.details`
                    for per-field issues.
                  value:
                    error:
                      code: validation.failed
                      message: >-
                        The request failed schema validation. See
                        `error.details` for per-field issues.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/validation-failed
        '401':
          description: |-
            Authentication failed.

            | Error code | When |
            | --- | --- |
            | `auth.unauthorized` | Credential is missing or malformed. |
          x-error-codes:
            - auth.unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.unauthorized:
                  summary: Credential is missing or malformed.
                  value:
                    error:
                      code: auth.unauthorized
                      message: Credential is missing or malformed.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-unauthorized
        '403':
          description: >-
            Authenticated, but not permitted.


            | Error code | When |

            | --- | --- |

            | `auth.forbidden` | Credential is valid but does not have access to
            the requested resource or action. |
          x-error-codes:
            - auth.forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.forbidden:
                  summary: >-
                    Credential is valid but does not have access to the
                    requested resource or action.
                  value:
                    error:
                      code: auth.forbidden
                      message: >-
                        Credential is valid but does not have access to the
                        requested resource or action.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-forbidden
        '429':
          description: |-
            Too many requests.

            | Error code | When |
            | --- | --- |
            | `rate_limit.exceeded` | Per-key rate limit exceeded. |
          x-error-codes:
            - rate_limit.exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit.exceeded:
                  summary: Per-key rate limit exceeded.
                  value:
                    error:
                      code: rate_limit.exceeded
                      message: Per-key rate limit exceeded.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/rate-limit-exceeded
        '500':
          description: >-
            Something went wrong on our end.


            | Error code | When |

            | --- | --- |

            | `internal.error` | An unexpected server error occurred. Retry with
            exponential backoff and include `request_id` in any support request.
            |
          x-error-codes:
            - internal.error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal.error:
                  summary: >-
                    An unexpected server error occurred. Retry with exponential
                    backoff and include `request_id` in any support request.
                  value:
                    error:
                      code: internal.error
                      message: >-
                        An unexpected server error occurred. Retry with
                        exponential backoff and include `request_id` in any
                        support request.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/internal-error
      security:
        - WalletIdentityBearer: []
components:
  schemas:
    CreateWalletSessionRequest:
      type: object
      properties:
        publishable_key:
          type: string
          minLength: 1
          description: The publishable key of the site the wallet is embedded in.
      required:
        - publishable_key
      example:
        publishable_key: end_pk_live_0123456789abcdef0123456789abcdef
    CreateWalletSessionResponse:
      type: object
      properties:
        token:
          type: string
          description: Credential the wallet presents to establish the customer's session.
        session_token:
          type: string
          description: Credential the wallet presents when resolving an operation to sign.
        expires_at:
          type: integer
          description: >-
            Unix seconds at which `session_token` lapses. `token` is
            shorter-lived and the wallet refreshes it on its own; do not treat
            this as its expiry.
        chain_id:
          type: integer
          description: Network the session operates on.
      required:
        - token
        - session_token
        - expires_at
        - chain_id
      example:
        token: eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...
        session_token: end_wsess_AbCd_example_token
        expires_at: 1755640000
        chain_id: 8453
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              anyOf:
                - $ref: '#/components/schemas/ErrorCode'
                - type: string
              description: >-
                Stable, namespaced error code. The `ErrorCode` catalogue lists
                every code defined today; handle an unrecognized value as a
                generic failure rather than throwing, since codes are added over
                time.
              example: chip.not_found
            message:
              type: string
              description: >-
                Human-readable description, for logs and debugging. Wording may
                change without notice - never parse or match against it.
              example: Chip not found
            request_id:
              type: string
              description: >-
                Identifier for this request, matching the `X-Request-Id`
                response header. Log it and include it in any support request.
              example: req_8e1a7f50-90ab-4cde-f012-3456789abcde
            doc_url:
              type: string
              description: Documentation page for this error code.
              example: https://docs.endstate.io/errors/chip-not-found
            details:
              $ref: '#/components/schemas/ValidationErrorDetails'
          required:
            - code
            - message
            - request_id
            - doc_url
      required:
        - error
      description: >-
        Every error response, regardless of endpoint or HTTP status, uses this
        envelope.
    ErrorCode:
      type: string
      enum:
        - validation.failed
        - auth.unauthorized
        - auth.forbidden
        - session_token.invalid_or_expired
        - session_token.wrong_chip
        - not_found.resource
        - rate_limit.exceeded
        - chip.not_found
        - chip.invalid_e_value
        - chip.already_scanned
        - quota.exceeded
        - chip.not_a_test_chip
        - unit.not_found
        - unit.already_exists
        - unit.not_minted
        - collection.not_found
        - collection.already_exists
        - collection.not_active
        - chip.already_paired
        - chip.bulk_mixed_collections
        - chip.bulk_pending
        - unit.issuance_pending
        - claim.owner_unknown
        - claim.already_to_recipient
        - claim.in_progress
        - claim.not_found
        - chip_replacement.locked
        - chip_replacement.in_progress
        - chip_replacement.not_found
        - transfer.owner_unknown
        - transfer.already_to_recipient
        - transfer.in_progress
        - transfer.not_found
        - idempotency.key_conflict
        - idempotency.in_progress
        - internal.error
      description: >-
        Stable, namespaced error code in `<resource>.<reason>` form. Branch on
        this rather than on `message` or the HTTP status. This is the catalogue
        as of this spec revision, not a closed set - see
        `ErrorResponse.error.code`.
      example: chip.not_found
    ValidationErrorDetails:
      type: object
      properties:
        formErrors:
          type: array
          items:
            type: string
          description: Issues that apply to the request as a whole rather than one field.
          example: []
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation issues keyed by the field that failed.
          example:
            name:
              - Required
      required:
        - formErrors
        - fieldErrors
      description: Per-field validation detail. Present only on `validation.failed`.
  securitySchemes:
    WalletIdentityBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use `Authorization: Bearer <identity token>` - a single-use, short-lived
        token identifying the customer, issued by your own sign-in.

````