# GlobAI OS auth.md — agent authentication

This document tells AI agents (and their operators) how to obtain and use credentials
for the GlobAI OS platform. The web console lives at `os.globai.<domain>`, the API at
`api.globai.<domain>`, and the identity provider at `auth.globai.<domain>`; derive the
sibling hosts from the host serving this file.

## Discovery metadata

- Authorization-server metadata (RFC 8414):
  `https://api.globai.<domain>/.well-known/openid-configuration`
- Protected-resource metadata (RFC 9728):
  `/.well-known/oauth-protected-resource` on this host
- API catalog (RFC 9727): `/.well-known/api-catalog` on this host

## Option 1 — API key (recommended for autonomous agents)

Agent registration is operator-mediated: a human with access to the GlobAI OS console
issues an API key scoped to an organization, with a role of `EXECUTE`, `READ_ONLY`,
or `ADMIN`. There is no self-service dynamic client registration today.

Use the key on every request:

```
GET https://api.globai.<domain>/v1/agents
X-API-Key: <your key>
```

## Option 2 — OAuth 2.0 authorization code + PKCE

For user-delegated access, run the authorization-code flow with PKCE (`S256` only)
against the endpoints advertised in the authorization-server metadata above.
Public clients omit the client secret; confidential clients post it
(`client_secret_post`). Scopes: `openid`, `email`, `profile`.

## MCP access

MCP servers live at `https://api.globai.<domain>/v1/mcp/<hub>/<plane>`
(hubs: `agentic`, `intelligence`, `corporate`; planes: `run`, `build`) over the
Streamable HTTP transport. Send a Bearer token (JWT or API key) carrying the
`mcp.tools` scope. Tokens that carry an `aud` claim must be bound to the exact
server they call (RFC 8707 resource indicators).

## Session security

Interactive users authenticate through the identity provider at
`auth.globai.<domain>` (OpenID Connect). Agents should prefer API keys or the
PKCE flow above; never scrape or replay browser sessions.