Backstage Authorization API

openapi: 3.2.0
info:
  title: Backstage Permissions Authorization API
  description: The Backstage Permissions API provides endpoints for evaluating and managing authorization decisions within Backstage. It enables plugins to check whether a given user or service has permission to perform a specific action. The framework supports policy-based authorization with conditional rules that can be applied to resources.
  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/permission
  description: Local development server
tags:
- name: Authorization
paths:
  /authorize:
    post:
      operationId: authorize
      summary: Backstage Evaluate permission requests
      description: Evaluates one or more permission requests and returns authorization decisions. Each request specifies a permission and optionally a resource reference. The permission policy is consulted to determine whether each request should be allowed, denied, or conditionally allowed with additional resource-level rules.
      tags:
      - Authorization
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/PermissionRequest'
                  description: Array of permission evaluation requests.
      responses:
        '200':
          description: Authorization decisions for each request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PermissionDecision'
        '400':
          description: Invalid request format.
        '401':
          description: Authentication required.
  /plugins/{pluginId}/apply-conditions:
    post:
      operationId: applyConditions
      summary: Backstage Apply conditional permission rules
      description: Applies conditional authorization rules for a specific plugin. When a permission decision includes conditions, those conditions must be evaluated against the actual resource data. This endpoint allows plugins to resolve conditional decisions into final allow/deny results.
      tags:
      - Authorization
      security:
      - bearerAuth: []
      parameters:
      - name: pluginId
        in: path
        required: true
        description: The plugin identifier that owns the resource type.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ConditionalRequest'
      responses:
        '200':
          description: Resolved authorization decisions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PermissionDecision'
        '400':
          description: Invalid request format.
        '401':
          description: Authentication required.
components:
  schemas:
    ConditionalRequest:
      type: object
      required:
      - resourceRef
      - resourceType
      - conditions
      properties:
        resourceRef:
          type: string
          description: Reference to the resource.
        resourceType:
          type: string
          description: The resource type identifier.
        conditions:
          type: object
          description: The conditions to evaluate against the resource.
    PermissionRequest:
      type: object
      required:
      - permission
      properties:
        permission:
          type: object
          required:
          - type
          - name
          properties:
            type:
              type: string
              enum:
              - basic
              - resource
              description: The permission type.
            name:
              type: string
              description: The unique permission name.
            resourceType:
              type: string
              description: The resource type for resource-based permissions.
            attributes:
              type: object
              properties:
                action:
                  type: string
                  enum:
                  - create
                  - read
                  - update
                  - delete
                  description: The action being performed.
        resourceRef:
          type: string
          description: Reference to the specific resource being accessed (e.g., component:default/my-service).
    PermissionDecision:
      type: object
      required:
      - result
      properties:
        result:
          type: string
          enum:
          - ALLOW
          - DENY
          - CONDITIONAL
          description: The authorization decision result.
        pluginId:
          type: string
          description: The plugin responsible for condition evaluation.
        resourceType:
          type: string
          description: The resource type for conditional decisions.
        conditions:
          type: object
          description: The conditions that must be evaluated against the resource to produce a final decision. Only present when result is CONDITIONAL.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Backstage Permissions Documentation
  url: https://backstage.io/docs/permissions/overview