openapi: 3.1.0
info:
  title: Backstage Auth Actions Tasks 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: Tasks
  description: Endpoints for creating and managing scaffolder tasks.
paths:
  /v2/tasks:
    get:
      operationId: listTasks
      summary: Backstage List scaffolder tasks
      description: Lists scaffolder tasks, optionally filtered by the user who created them. Returns task metadata and status information.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      parameters:
      - name: createdBy
        in: query
        required: false
        description: Filter tasks by the user who created them.
        schema:
          type: string
      responses:
        '200':
          description: A list of scaffolder tasks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTask
      summary: Backstage Create a scaffolder task
      description: Creates a new scaffolder task to execute a software template. The task runs asynchronously and its progress can be monitored through the event stream or logs endpoints.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - templateRef
              - values
              properties:
                templateRef:
                  type: string
                  description: The entity reference of the template to execute.
                  example: template:default/create-react-app
                values:
                  type: object
                  description: The input values for the template parameters.
                  additionalProperties: true
                secrets:
                  type: object
                  description: Secret values to pass to the template (not persisted).
                  additionalProperties:
                    type: string
      responses:
        '201':
          description: Task created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the created task.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}:
    get:
      operationId: getTask
      summary: Backstage Get task by ID
      description: Retrieves the details and current status of a scaffolder task.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      parameters:
      - name: taskId
        in: path
        required: true
        description: The unique identifier of the task.
        schema:
          type: string
      responses:
        '200':
          description: The task details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/cancel:
    post:
      operationId: cancelTask
      summary: Backstage Cancel a task
      description: Requests cancellation of a running scaffolder task.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancellation requested successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/eventstream:
    get:
      operationId: getTaskEventStream
      summary: Backstage Get task event stream
      description: Returns a server-sent event stream of task progress events. This endpoint streams real-time updates about the task execution including step progress, log messages, and completion status.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Only return events after this sequence number.
        schema:
          type: integer
      responses:
        '200':
          description: A server-sent event stream of task events.
          content:
            text/event-stream:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/logs:
    get:
      operationId: getTaskLogs
      summary: Backstage Get task logs
      description: Retrieves the log entries for a scaffolder task, providing detailed information about each step of template execution.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Only return log entries after this sequence number.
        schema:
          type: integer
      responses:
        '200':
          description: Task log entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    createdAt:
                      type: string
                      format: date-time
                    body:
                      type: object
                      properties:
                        message:
                          type: string
                        stepId:
                          type: string
                        status:
                          type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/dry-run:
    post:
      operationId: dryRunTask
      summary: Backstage Dry-run a template
      description: Executes a template as a dry run without actually performing any side effects. Useful for testing and validating templates before actual execution.
      tags:
      - Tasks
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - template
              - values
              properties:
                template:
                  type: object
                  description: The template entity to dry-run.
                values:
                  type: object
                  description: Input values for the template parameters.
                  additionalProperties: true
                secrets:
                  type: object
                  description: Secret values to pass to the template.
                  additionalProperties:
                    type: string
                directoryContents:
                  type: array
                  description: Initial directory contents for the workspace.
                  items:
                    type: object
                    properties:
                      path:
                        type: string
                      base64Content:
                        type: string
      responses:
        '200':
          description: Dry-run result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  log:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        body:
                          type: object
                  directoryContents:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        base64Content:
                          type: string
                  steps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                  output:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the task.
        spec:
          type: object
          properties:
            apiVersion:
              type: string
            templateInfo:
              type: object
              properties:
                entityRef:
                  type: string
                  description: Reference to the template entity.
            steps:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  action:
                    type: string
                  input:
                    type: object
            output:
              type: object
              additionalProperties: true
            parameters:
              type: object
              additionalProperties: true
        status:
          type: string
          description: The current status of the task.
          enum:
          - open
          - processing
          - completed
          - failed
          - cancelled
        createdAt:
          type: string
          format: date-time
        lastHeartbeatAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        createdBy:
          type: string
          description: The user who created the task.
  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/