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

# JSON Web Key Set

> Public keys for verifying JWTs issued by Stell (RFC 7517). Match the token header kid against a key kid. Does not require authentication; cacheable for one hour.



## OpenAPI

````yaml /api-reference/openapi.json get /.well-known/jwks.json
openapi: 3.0.1
info:
  title: Stell API
  description: >-
    Create and manage passes for Apple Wallet and Google Wallet. One API for
    loyalty programs, membership cards, tickets, and more.


    ## Errors


    Errors returned by Stell use one JSON shape:


    ```json

    {
      "error": {
        "code": "NOT_FOUND",
        "message": "Pass not found",
        "details": { "passId": "3f1c2b8e-9a4d-4c5e-8f7a-1b2c3d4e5f60" }
      },
      "requestId": "01J9Z3K8QH5X2V7RMT4N6WBCDE"
    }

    ```


    `code` is one of `BAD_REQUEST`, `VALIDATION_ERROR`, `UNAUTHORIZED`,
    `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `UNPROCESSABLE_ENTITY` or
    `INTERNAL_ERROR`. `details` is optional and its fields depend on the error:
    for example `missingFields` for required fields left out, `errors` for pass
    template validation, the `passId` that was not found, `index` for the
    duplicate geofence on `PUT /v1/passes/{passId}/geofences`, or `geofenceId`
    for the existing geofence a new or updated one duplicates.


    API Gateway rejects some requests before they reach Stell: a missing or
    invalid API key, a throttled request (429), and a request body or required
    parameter that does not match the published schema (400, for example
    `{"message": "Invalid request body"}`). These get a short error body from
    API Gateway instead, with no `error` object and no `requestId`.


    ## Request IDs


    Responses from Stell carry a request ID in the `X-Request-Id` header, except
    `GET /v1/health` and `204 No Content` responses. Error bodies from Stell
    repeat it as `requestId`, and so do success bodies except `GET
    /v1/merchants/{merchantId}`, which returns the merchant without a wrapper.
    Include the request ID when you contact Stell support about a request.


    ## Pagination


    List endpoints that accept `limit` return one page at a time. `limit` sets
    the page size, from 1 to 100, and defaults to 100; a value outside that
    range returns 400. When more results exist, the response includes a
    `nextToken`. Send it back as the `nextToken` query parameter to get the next
    page, and stop when a response has no `nextToken`. A page can hold fewer
    items than `limit` and still have a `nextToken`. `GET /v1/companies` returns
    only your own company, so it ignores `limit` and never returns a
    `nextToken`.
  termsOfService: https://getstell.com/terms
  contact:
    name: Stell API Support
    url: https://getstell.com/about?topic=Technical%20Support#contact
    email: hello@getstell.com
  version: '2026-10-23T14:07:13Z'
servers:
  - url: https://api.platform.getstell.com
    description: Production API
security:
  - StellApiAuthorizer: []
tags:
  - name: Companies
    description: Manage companies at the top of your tenant hierarchy.
  - name: Merchants
    description: Manage brands and business units within companies.
  - name: Stores
    description: Manage store locations and customer touchpoints.
  - name: Programs
    description: Configure pass programs for loyalty, membership, tickets, and more.
  - name: Pass Templates
    description: Define pass design and field layouts.
  - name: Passes
    description: Issue and manage customer passes for Apple and Google Wallet.
  - name: Terminals
    description: Configure terminals for tap-to-scan functionality.
  - name: Transactions
    description: Track pass usage, purchases, and redemptions.
  - name: Engagement
    description: Geofences, notifications, and location-based engagement features.
  - name: System
    description: Health checks and service monitoring.
paths:
  /.well-known/jwks.json:
    get:
      tags:
        - System
      summary: JSON Web Key Set
      description: >-
        Public keys for verifying JWTs issued by Stell (RFC 7517). Match the
        token header kid against a key kid. Does not require authentication;
        cacheable for one hour.
      operationId: getJwks
      responses:
        '200':
          description: 'JWKS document: { keys: [...] }'
          content: {}
        '503':
          description: Signing keys temporarily unavailable
          content: {}
components:
  securitySchemes:
    StellApiAuthorizer:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        API key authentication. Include your API key as a Bearer token.

        Example: `Bearer sk_prod_xxxxxx`

        Get your API key from the Stell Dashboard.

````

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