Backstage Auth API — Authentication

naftiko: 1.0.0-alpha2
info:
  label: Backstage Auth API — Authentication
  description: 'Backstage Auth API — Authentication. 4 operations. Lead operation: Backstage Handle authentication callback
    (popup flow). Self-contained Naftiko capability covering one Backstage business surface.'
  tags:
  - Backstage
  - Authentication
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    BACKSTAGE_API_KEY: BACKSTAGE_API_KEY
capability:
  consumes:
  - type: http
    namespace: auth-authentication
    baseUri: https://localhost:7007/api/auth
    description: Backstage Auth API — Authentication business capability. Self-contained, no shared references.
    resources:
    - name: provider-handler-frame
      path: /{provider}/handler/frame
      operations:
      - name: handleproviderframe
        method: GET
        description: Backstage Handle authentication callback (popup flow)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: provider
          in: path
          type: string
          description: The authentication provider identifier.
          required: true
        - name: code
          in: query
          type: string
          description: The authorization code returned by the provider.
        - name: state
          in: query
          type: string
          description: The state parameter for CSRF protection.
    - name: provider-logout
      path: /{provider}/logout
      operations:
      - name: logoutprovider
        method: POST
        description: Backstage Logout from provider
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: provider
          in: path
          type: string
          description: The authentication provider identifier.
          required: true
    - name: provider-refresh
      path: /{provider}/refresh
      operations:
      - name: refreshprovidertoken
        method: GET
        description: Backstage Refresh authentication token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: provider
          in: path
          type: string
          description: The authentication provider identifier.
          required: true
        - name: optional
          in: query
          type: boolean
          description: If set, the refresh will not fail if no refresh token is available but will return an empty response
            instead.
    - name: provider-start
      path: /{provider}/start
      operations:
      - name: startproviderauth
        method: GET
        description: Backstage Start authentication flow
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: provider
          in: path
          type: string
          description: The authentication provider identifier (e.g., github, google, okta).
          required: true
        - name: flow
          in: query
          type: string
          description: The authentication flow type.
        - name: env
          in: query
          type: string
          description: The target environment for the authentication flow.
    authentication:
      type: bearer
      token: '{{env.BACKSTAGE_API_KEY}}'
  exposes:
  - type: rest
    namespace: auth-authentication-rest
    port: 8080
    description: REST adapter for Backstage Auth API — Authentication. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/{provider}/handler/frame
      name: provider-handler-frame
      description: REST surface for provider-handler-frame.
      operations:
      - method: GET
        name: handleproviderframe
        description: Backstage Handle authentication callback (popup flow)
        call: auth-authentication.handleproviderframe
        with:
          provider: rest.provider
          code: rest.code
          state: rest.state
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/{provider}/logout
      name: provider-logout
      description: REST surface for provider-logout.
      operations:
      - method: POST
        name: logoutprovider
        description: Backstage Logout from provider
        call: auth-authentication.logoutprovider
        with:
          provider: rest.provider
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/{provider}/refresh
      name: provider-refresh
      description: REST surface for provider-refresh.
      operations:
      - method: GET
        name: refreshprovidertoken
        description: Backstage Refresh authentication token
        call: auth-authentication.refreshprovidertoken
        with:
          provider: rest.provider
          optional: rest.optional
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/{provider}/start
      name: provider-start
      description: REST surface for provider-start.
      operations:
      - method: GET
        name: startproviderauth
        description: Backstage Start authentication flow
        call: auth-authentication.startproviderauth
        with:
          provider: rest.provider
          flow: rest.flow
          env: rest.env
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: auth-authentication-mcp
    port: 9090
    transport: http
    description: MCP adapter for Backstage Auth API — Authentication. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: backstage-handle-authentication-callback-popup
      description: Backstage Handle authentication callback (popup flow)
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: auth-authentication.handleproviderframe
      with:
        provider: tools.provider
        code: tools.code
        state: tools.state
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-logout-provider
      description: Backstage Logout from provider
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: auth-authentication.logoutprovider
      with:
        provider: tools.provider
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-refresh-authentication-token
      description: Backstage Refresh authentication token
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: auth-authentication.refreshprovidertoken
      with:
        provider: tools.provider
        optional: tools.optional
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-start-authentication-flow
      description: Backstage Start authentication flow
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: auth-authentication.startproviderauth
      with:
        provider: tools.provider
        flow: tools.flow
        env: tools.env
      outputParameters:
      - type: object
        mapping: $.