Service API

API key authenticated backend endpoints for service-owned operations.

Updated May 10, 2026 Edit this page

Service API

The service API is for server-to-server calls authenticated with X-API-Key.

Authentication

curl -X GET https://sso.example.com/api/service/info \
  -H "X-API-Key: sk_live_abc123"

Core endpoints

Method Path Purpose
GET /api/service/users List users linked to the service
POST /api/service/users Create or provision a user
GET /api/service/users/:user_id Get one user
PATCH /api/service/users/:user_id Update a user
DELETE /api/service/users/:user_id Delete a user
GET /api/service/subscriptions List subscriptions
POST /api/service/subscriptions Create a subscription
GET /api/service/subscriptions/:user_id Get one user subscription
PATCH /api/service/subscriptions/:user_id Update a subscription
DELETE /api/service/subscriptions/:user_id Delete a subscription
GET /api/service/analytics Get service analytics
GET /api/service/info Read service configuration
PATCH /api/service/info Update service configuration
POST /api/service/provider-tokens Request a backend-only provider token for a user

Provider token requests

POST /api/service/provider-tokens is used when a backend needs a third-party access token for an AuthOS user.

Example request:

{
  "user_id": "user_123",
  "provider": "github",
  "scopes": ["repo"],
  "redirect_uri": "https://app.acme.com/callback",
  "state": "opaque-client-state"
}

Possible responses:

  • status: "ok" with an access token when an existing grant satisfies the request
  • status: "action_required" with a reauth_url when the user must approve scopes or link an account

When action_required is returned, send the user to the returned reauth_url exactly as provided. AuthOS generates a short-lived hosted URL in the form /connect/provider-token/:state; that URL is bound to the original service, user, provider, requested scopes, service callback URI, and optional client state.

Do not replace this URL with /settings/connections or any other AuthOS dashboard route. Provider-token reauth is an end-user service flow, not an organization-console flow. It must not require the user to create or select an AuthOS organization.

After the user completes provider authorization, AuthOS creates or updates the connected account, creates the service grant for the requested scope subset, completes the one-time request, and redirects to the registered service callback URI with provider_grant=success, provider, and the original client state when supplied.

This endpoint is paired with the hosted and authenticated provider-token request completion flows documented on User Management API.