openapi: 3.1.0
info:
  title: Backstage Auth Actions Token Verification API
  description: The Backstage Auth API provides endpoints for authenticating users and services with the Backstage backend. It supports multiple authentication providers (GitHub, Google, Okta, SAML, etc.) and handles OAuth flows, token issuance, token refresh, and session management. The Auth API is used by the Backstage frontend to initiate login flows and by backend plugins to verify caller identity via Backstage tokens.
  version: 1.0.0
  contact:
    name: Backstage
    url: https://backstage.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://localhost:7007/api/auth
  description: Local development server
tags:
- name: Token Verification
paths:
  /.well-known/backstage/auth/v1/jwks.json:
    get:
      operationId: getJwks
      summary: Backstage Get JSON Web Key Set
      description: Returns the JSON Web Key Set (JWKS) used to verify Backstage tokens. This endpoint is used by backend services to validate tokens issued by the auth backend.
      tags:
      - Token Verification
      responses:
        '200':
          description: The JWKS containing public keys for token verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwksResponse'
components:
  schemas:
    JwksResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              kty:
                type: string
              kid:
                type: string
              alg:
                type: string
              use:
                type: string
              n:
                type: string
              e:
                type: string
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: backstage-auth
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Backstage Auth Documentation
  url: https://backstage.io/docs/auth/