Backstage Metadata API

openapi: 3.1.0
info:
  title: Backstage Auth Actions Metadata 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: Metadata
paths:
  /metadata/techdocs/{namespace}/{kind}/{name}:
    get:
      operationId: getTechDocsMetadata
      summary: Backstage Get TechDocs metadata for an entity
      description: Returns the TechDocs metadata for a specific catalog entity, including the site name, description, and build information.
      tags:
      - Metadata
      security:
      - bearerAuth: []
      parameters:
      - name: namespace
        in: path
        required: true
        description: The entity namespace.
        schema:
          type: string
          default: default
      - name: kind
        in: path
        required: true
        description: The entity kind (e.g., Component, API).
        schema:
          type: string
      - name: name
        in: path
        required: true
        description: The entity name.
        schema:
          type: string
      responses:
        '200':
          description: TechDocs metadata for the entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TechDocsMetadata'
        '404':
          description: No TechDocs found for the specified entity.
  /metadata/entity/{namespace}/{kind}/{name}:
    get:
      operationId: getEntityMetadata
      summary: Backstage Get entity metadata for TechDocs
      description: Returns catalog entity metadata relevant to TechDocs rendering, including the entity name, description, and TechDocs annotations.
      tags:
      - Metadata
      security:
      - bearerAuth: []
      parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: kind
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Entity metadata for TechDocs.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Entity not found.
components:
  schemas:
    TechDocsMetadata:
      type: object
      properties:
        site_name:
          type: string
          description: The name of the documentation site.
        site_description:
          type: string
          description: Description of the documentation site.
        etag:
          type: string
          description: ETag for cache validation.
        build_timestamp:
          type: string
          format: date-time
          description: Timestamp of the last documentation build.
        files:
          type: array
          items:
            type: string
          description: List of files in the documentation bundle.
  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/