Authentication

Authentication in the current product is primarily user-session based. The app passes a bearer token from the signed-in user session to the backend, and the backend resolves the authorized organization plus the permissions or entitlements required for the action.

This page is intentionally mixed-mode. User-session authentication reflects the current implementation. Service key and API key guidance describes the target product model the docs are meant to standardize around.

Current model

Most current calls from the app use:

  • Authorization: Bearer <user access token>
  • an explicit organizationId
  • backend-side permission and entitlement checks

For AI platform endpoints, the backend resolves either a user principal or a service-key principal depending on the credential presented.

User bearer tokens

User bearer tokens are the current default for app-driven requests. They are appropriate when:

  • a signed-in person is using the web app
  • the backend should enforce user permissions
  • actions should inherit the user and organization context of the current session

User-scoped request

curl "$API_BASE/api/prompts?organizationId=org_123" \
  -H "Authorization: Bearer $USER_TOKEN"

In the current product, this is the credential type used for:

  • prompts, tools, runs, realtime sessions, and models from the app
  • onboarding completion
  • billing portal and checkout flows
  • support ticket creation and replies
  • most user-management actions

Service keys

Service keys are the target backend automation credential for the AI platform. They are org-scoped, long-lived, and intended for trusted server environments only.

Use service keys for:

  • CI and deployment workflows
  • internal admin tools
  • server-side prompt and agent management
  • backend-triggered runs and runtime inspection

The current app already exposes a Service Keys management page and backend endpoints for listing, creating, fetching, and revoking keys.

Service key request

curl "$API_BASE/api/prompts?organizationId=org_123" \
  -H "Authorization: Bearer $SERVICE_KEY"

API keys

API keys are the intended application credential for developer-managed integrations. They should be treated as product-facing credentials for integrating your own application with the platform without depending on a user session.

Target-state characteristics:

  • environment-aware, typically test or live
  • rotatable and revocable
  • safe for server-side application use, not direct browser embedding
  • appropriate for public API integrations and SDKs

The app already includes API key list, create, rotate, and revoke flows, and the docs treat that as the foundation for the future public API.

Choosing the right credential

  • Name
    User bearer token
    Type
    current
    Description

    Use for signed-in product users interacting with the app.

  • Name
    Service key
    Type
    target-state + partial current support
    Description

    Use for backend automation that manages AI platform resources inside one organization.

  • Name
    API key
    Type
    target-state + partial current support
    Description

    Use for application integrations and future public SDK access.

The high-level rule is simple: user tokens for people, service keys for trusted internal automation, and API keys for developer-facing application integrations.

Was this page helpful?