# auth.md

You are an agent. Goyondo supports **agent registration** via OAuth 2.0 Device Authorization Grant (RFC 8628). Follow the steps in order.

## Step 1 — Discover

Fetch the Protected Resource Metadata and Authorization Server metadata.

### 1a. Protected Resource Metadata

```http
GET https://goyondo.run/.well-known/oauth-protected-resource
```

Key fields:

- `resource` — canonical API base (`https://goyondo.run/api`)
- `authorization_servers` — OAuth authorization server issuer(s)
- `scopes_supported` — scopes available on issued credentials
- `bearer_methods_supported` — use `Authorization: Bearer …` in API requests

### 1b. Authorization Server Metadata

```http
GET https://goyondo.run/.well-known/oauth-authorization-server
```

Read the `agent_auth` block for registration endpoints, supported methods, and credential types.

## Step 2 — Register (device authorization)

Goyondo uses a user-in-the-loop device flow. The user approves access in a browser; no copy-paste of secrets is required.

```http
POST https://goyondo.run/api/agent-auth/device
Content-Type: application/json

{
  "agent_name": "My Travel Agent",
  "requested_scopes": ["trips:read", "trips:write"]
}
```

Response (200):

```json
{
  "device_code": "<opaque 64-char hex>",
  "user_code": "GYD-XXXX",
  "verification_uri": "https://goyondo.run/connect",
  "verification_uri_complete": "https://goyondo.run/connect?code=GYD-XXXX",
  "expires_in": 600,
  "interval": 5
}
```

Show the user `verification_uri_complete` (or `user_code` with `verification_uri`) and ask them to tap **Grant access**.

## Step 3 — Poll for credential

Poll until the user approves or the code expires:

```http
POST https://goyondo.run/api/agent-auth/token
Content-Type: application/json

{ "device_code": "<device_code from step 2>" }
```

While pending:

```json
{ "error": "authorization_pending" }
```

On approval:

```json
{
  "access_token": "gyd_…",
  "token_type": "bearer",
  "scope": "trips:read trips:write"
}
```

Use `access_token` as the bearer credential. Poll every `interval` seconds; respect `expires_in`.

## Step 4 — Use the credential

```http
POST https://goyondo.run/api/agent/task
Authorization: Bearer gyd_…
Content-Type: application/json

{ "capability": "get_trip", "arguments": { "trip_id": "…" } }
```

Alternative interfaces:

- MCP-style tools: `GET/POST https://goyondo.run/api/mcp/tools`
- REST: `https://goyondo.run/api/openapi.json`

## Revocation

Users revoke agent credentials at **Profile → API Keys** (`https://goyondo.run/profile?tab=api-keys`). A revoked key returns `401` on the next API call — drop the credential and restart at Step 1.

## Errors

| Code | Where | What to do |
| ---- | ----- | ---------- |
| `authorization_pending` | `/api/agent-auth/token` | User has not approved yet; keep polling. |
| `slow_down` | `/api/agent-auth/token` | Increase poll interval. |
| `expired_token` | `/api/agent-auth/token` | Device code expired; restart at Step 2. |
| `access_denied` | `/api/agent-auth/token` | User denied; restart at Step 2. |
| `invalid_grant` | `/api/agent-auth/token` | Unknown or reused `device_code`; restart at Step 2. |
| `401` | API calls | Credential invalid or revoked; restart at Step 1. |

Full integration guide: `https://goyondo.run/llms.txt`