authos-device-flow

AuthOS Device Flow

Public AuthOS Links

Use these public AuthOS links when producing user-facing setup or troubleshooting guidance:

• Main site: https://authos.dev/
• Documentation: https://authos.dev/docs/
• AI Agent Skills guide: https://authos.dev/docs/ai-agent-skills/
• AuthOS source repository: https://github.com/drmhse/AuthOS

Use this skill for OAuth 2.0 device authorization flows backed by AuthOS. Device flow is implemented in source with three public endpoints and matching SDK helpers.

Endpoints

• POST /auth/device/code: create a device code.
• POST /auth/device/verify: validate a user-facing code and return org/service/provider context.
• POST /auth/token: exchange an authorized device code for a bearer token.

The SDK exposes these as authos.auth.deviceCode.request, verify, and exchangeToken.

Request a Device Code

const device = await authos.auth.deviceCode.request({
  client_id: 'service-client-id',
  org: 'acme',
  service: 'cli'
});

console.log(`Open ${device.verification_uri}`);
console.log(`Enter ${device.user_code}`);

The request fields are client_id, org, and service.

For a service-level device flow, AuthOS validates the service by client ID, org slug, and service slug, then uses that service's device_activation_uri. Configure that URI on the service before offering CLI login.

For platform admin CLI login, source supports org = "platform", service = "admin-cli", and a client_id starting with platform-; the verification URI comes from PLATFORM_DASHBOARD_BASE_URL + /activate.

Activation Page

On the activation page, call:

const context = await authos.auth.deviceCode.verify(userCode);

The response contains:

{
  org_slug: string;
  service_slug: string;
  available_providers: string[];
}

Start OAuth using the returned context and include user_code in the login URL:

const url = authos.auth.getLoginUrl('github', {
  org: context.org_slug,
  service: context.service_slug,
  user_code: userCode
});