Stellary Authentication

generated: '2026-09-01'
method: searched
source: https://stellary.co/docs/api/ + https://stellary.co/docs/mcp/ + probed https://api.stellary.co/.well-known/oauth-authorization-server
docs: https://stellary.co/docs/api/
note: >-
  Derived by hand from the provider's own reference pages and the live RFC 8414 metadata, not
  from an OpenAPI securitySchemes block -- Stellary publishes no machine-readable contract
  (Swagger UI is mounted at /api/docs in non-production builds only, per their API reference).
summary: >-
  One Bearer scheme covers both surfaces. The backend guard tries the Authorization header first
  and falls back to the web app's authenticated session cookie. For MCP clients, OAuth 2.1 with
  PKCE and dynamic client registration is the recommended and discoverable path.
schemes:
- id: bearer
  type: http
  scheme: bearer
  in: header
  header: Authorization
  format: 'Bearer <jwt-or-personal-access-token>'
  applies_to: [REST, MCP]
  accepted_credentials:
  - kind: user_jwt
    issued_by: POST /auth/login and the other /auth flows
    identity: human user
    note: Response returns a temporary two-factor token instead of a session when 2FA is required.
  - kind: personal_access_token
    issued_by: POST /api-tokens
    identity: human user
    prefix: sl_
    prefix_evidence: 'Docs example response returns tokenPrefix "sl_abcd12"; the secret is returned once at creation only.'
    scoped: true
    expiry: optional ISO expiresAt at creation
    valid_for: [REST, MCP]
  - kind: agent_token
    identity: workspace agent
    used_for: queued missions, stellary_init, installed plugin tools
  - kind: mcp_token
    identity: anonymous transport context
    note: >-
      Transport gate only. Documented as insufficient for tools that require a user or agent
      identity, and only reachable when NODE_ENV is not production and MCP_TOKEN is unset.
- id: oauth2
  type: oauth2
  profile: OAuth 2.1
  applies_to: [MCP]
  flows:
    authorizationCode:
      authorizationUrl: https://api.stellary.co/authorize
      tokenUrl: https://api.stellary.co/token
      refreshUrl: https://api.stellary.co/token
      pkce: required (S256)
      scopes:
        projects:read: Read projects, boards, cards and delivery context
        projects:write: Create and modify projects, cards, comments and assignments
        pilotage:read: Read cockpit/pilotage state, dashboards and proposals
        pilotage:write: Create and act on pilotage actions and proposals
        offline_access: Issue a rotating refresh token
  dynamic_client_registration:
    supported: true
    endpoint: https://api.stellary.co/register
    standard: RFC 7591
  revocation_endpoint: https://api.stellary.co/revoke
  token_endpoint_auth_methods_supported: [client_secret_post, none]
  access_token_lifetime: 1 hour
  refresh: rotating refresh token when offline_access is granted
- id: session_cookie
  type: apiKey
  in: cookie
  applies_to: [REST]
  note: >-
    Fallback used by the first-party web app. A CSRF token is returned by /auth/login and
    /auth/me. Not intended for third-party integrations.
identity_model:
  note: >-
    An OAuth connection belongs to one workspace and may authorize the human, one or more active
    workspace agents, or both. With a single identity actingAs is implicit; with several it is
    required on every call, including stellary_init and mission tools.
  resolver_tool: stellary_list_identities
  rechecked_per_call: [credential scopes, project access, workspace permissions, agent status, agent tool policy, autonomy mode, mission snapshot]
mfa:
  supported: true
  note: Two-factor authentication is supported on user accounts; /auth/login returns a temporary two-factor token when it is required.