User Management API

These endpoints require a user JWT unless noted otherwise.

Core profile and security endpoints

Identity linking

Connected accounts and provider-token workflows

These endpoints power the newer third-party connected-account model and the completion flow used when a service requests a provider token with additional scopes.

Hosted provider-token reauth

Services that call POST /api/service/provider-tokens may receive an action_required response with a reauth_url. That URL points to:

This route is intentionally outside the AuthOS organization dashboard. It consumes the short-lived provider-token request state, starts the required provider OAuth flow with the original user/service/scope metadata, and returns the user to the service callback after AuthOS completes the grant.

The hosted route must not redirect an end user into organization creation, organization selection, or general connected-account management. If a service needs Microsoft To Do access, for example, the user should see Microsoft authorization and then return to the service, not the AuthOS admin console.

The authenticated /api/user/provider-token-requests/:state/* endpoints remain available for dashboard and SDK flows that already have the correct AuthOS user session. They are not required for the hosted service-return flow.

Example: list connected accounts

curl -X GET https://sso.example.com/api/user/linked-accounts \
  -H "Authorization: Bearer {jwt}"

Example response:

{
  "accounts": [
    {
      "id": "acct_123",
      "provider": "github",
      "provider_user_id": "12345",
      "email": "user@example.com",
      "display_name": "Octo User",
      "scopes": ["repo", "read:user"],
      "expires_at": null,
      "status": "active",
      "grants": []
    }
  ],
  "available_providers": [
    {
      "provider": "github",
      "display_name": "GitHub",
      "provider_type": "oauth2",
      "scopes": ["user:email"],
      "connect_supported": true
    }
  ]
}

Example: complete a provider-token request

curl -X POST https://sso.example.com/api/user/provider-token-requests/state_123/complete \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "acct_123"
  }'

Expected response:

{
  "redirect_url": "https://app.acme.com/callback?provider_token_request=completed"
}

Hosted provider-token reauth redirects directly to the stored service callback instead of returning this JSON response.

Related docs

• Authentication
• Service API
• Organizations