# auth.md — Orgo agent authentication

Authentication and registration guidance for AI agents and programmatic
clients of the Orgo API (https://www.orgo.ai).

## Audience

This document is for AI agents, SDKs, and scripts that call the Orgo REST API
to provision and control cloud computers (virtual desktops).

## Authoritative discovery metadata

- Protected Resource Metadata (RFC 9728): https://www.orgo.ai/.well-known/oauth-protected-resource
- Authorization Server Metadata (RFC 8414): https://www.orgo.ai/.well-known/oauth-authorization-server
- API catalog (RFC 9727): https://www.orgo.ai/.well-known/api-catalog
- OpenAPI description: https://www.orgo.ai/openapi.json
- Human docs: https://docs.orgo.ai

## Browser authorization for MCP

Connect your MCP client to https://www.orgo.ai/mcp. Authorize in your browser and select
one workspace. No API key needs to be copied. The server supports OAuth 2.1
code grants with S256 PKCE, Client ID Metadata Documents, and registration
for older clients. Access tokens expire after one hour; rotating refresh tokens
expire with the connection after 30 days. Revoke access in Settings → Credentials.
The MCP resource is https://www.orgo.ai/mcp and its scope is mcp:tools.

## Credential: Bearer API key

Scripts can continue to send an Orgo API key as a Bearer token:

    Authorization: Bearer <ORGO_API_KEY>

## Getting a credential

There are two registration paths (both yield an API key):

### 1. Orgo CLI device approval — for CLIs/agents on a device

1. POST https://www.orgo.ai/api/cli/auth/start with { "client": "<name>", "hostname": "<host>" }.
   The response includes `device_code`, `user_code`, `verification_uri`, and a poll `interval_seconds`.
2. Direct the user to the verification page https://www.orgo.ai/cli/approve (or `verification_uri_complete`)
   to approve the request while signed in.
3. Poll POST https://www.orgo.ai/api/cli/auth/poll with { "device_code": "<device_code>" } until it
   returns the issued API key.

### 2. Direct API-key creation — for server-side integrations

Create or rotate a key from the dashboard, or POST https://www.orgo.ai/api/keys while authenticated
(optionally workspace-scoped). The plaintext key is returned once at creation.

## Scopes

API keys grant access to the account's (or scoped workspace's) computers and
workspaces. API keys are separate from the MCP OAuth scope.

## Using the key

Send the key on every request to https://www.orgo.ai/api/* in the `Authorization: Bearer`
header. Treat keys as secrets; rotate via the dashboard or POST /api/keys if leaked.