> ## 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.

# Register your own token issuer

> Registers the token issuer your own system mints identity tokens with, switching your organization to external auth. Endstate verifies those tokens against the JWKS URL and audience you provide. Send all three fields; they replace any previously registered issuer.



## OpenAPI

````yaml /openapi.json put /v1/settings/auth
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/settings/auth:
    put:
      tags:
        - Settings
      summary: Register your own token issuer
      description: >-
        Registers the token issuer your own system mints identity tokens with,
        switching your organization to external auth. Endstate verifies those
        tokens against the JWKS URL and audience you provide. Send all three
        fields; they replace any previously registered issuer.
      operationId: updateAuthSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAuthSettingsRequest'
            example:
              issuer: https://auth.brand.example
              jwks_url: https://auth.brand.example/.well-known/jwks.json
              audience: https://wallet.brand.example
      responses:
        '200':
          description: The registered configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSettingsResponse'
              example:
                auth_type: external
                issuer: https://auth.brand.example
                jwks_url: https://auth.brand.example/.well-known/jwks.json
                audience: https://wallet.brand.example
        '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
        '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:
        - ApiKeyBearer: []
components:
  schemas:
    UpdateAuthSettingsRequest:
      type: object
      properties:
        issuer:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The `iss` your identity tokens carry. Matched exactly, so it must be
            stable across key rotation.
          example: https://auth.brand.example
        jwks_url:
          type: string
          maxLength: 2048
          format: uri
          description: >-
            A public, cacheable JWKS URL Endstate fetches to verify your tokens.
            HTTPS only.
          example: https://auth.brand.example/.well-known/jwks.json
        audience:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The `aud` your identity tokens carry. Use a value dedicated to
            Endstate so your other tokens cannot be presented here.
          example: https://wallet.brand.example
      required:
        - issuer
        - jwks_url
        - audience
      additionalProperties: false
    AuthSettingsResponse:
      type: object
      properties:
        auth_type:
          type: string
          enum:
            - endstate
            - external
          description: >-
            `external` when your own token issuer is registered; `endstate` when
            identity is managed by Endstate.
          example: external
        issuer:
          type:
            - string
            - 'null'
          description: The registered token issuer (`iss`), or null when unset.
          example: https://auth.brand.example
        jwks_url:
          type:
            - string
            - 'null'
          description: The registered JWKS URL, or null when unset.
          example: https://auth.brand.example/.well-known/jwks.json
        audience:
          type:
            - string
            - 'null'
          description: The audience (`aud`) your identity tokens carry, or null when unset.
          example: https://wallet.brand.example
      required:
        - auth_type
        - issuer
        - jwks_url
        - audience
    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:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: end_sk
      description: >-
        Use `Authorization: Bearer end_sk_*` for partner API keys (e.g.
        `end_sk_AbCd_example_api_key`).

````