# auth.md — authentication for agents and API clients (node.uk)

This file describes how automated clients (including AI agents) authenticate
to Node Digital's APIs. Human-readable hub: <https://node.uk/agents/>.
The metered API/AI gateway lives at `https://api.node.uk`; identity is
Keycloak at `https://auth.node.uk`.

## Registration

There is no anonymous or dynamic client registration. Credentials are issued
through a Node workspace:

1. A human signs up at <https://my.node.uk/signup> (£25 welcome credit;
   card required, nothing charged).
2. In the portal, create a **gateway credential** for each person, service or
   agent. Every actor gets its own credential so usage is attributed and
   billed per actor, and revoking a credential cuts off that actor only.

Questions or higher rate limits: <https://node.uk/contact-us/>.

## Getting a token

Credentials are OAuth 2.0 clients on your workspace's Keycloak realm. Use the
`client_credentials` grant:

```
POST https://auth.node.uk/realms/{your-realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

OIDC discovery for a realm:
`https://auth.node.uk/realms/{your-realm}/.well-known/openid-configuration`
(the shared customer realm is `customers`; workspaces have their own realm —
your portal shows which one your credentials belong to).

Gateway action scopes (ADR-0029): `api-gw.chat`, `api-gw.embeddings`,
`api-gw.run`, `api-gw.audio`, `api-gw.notify`, `api-gw.*`.

## Calling the API

Send the access token as a Bearer token:

```
POST https://api.node.uk/api/v1/models/{model}/chat/completions
Authorization: Bearer {access_token}
```

The gateway is OpenAI-compatible (chat completions, embeddings, audio
transcription, streaming). `GET https://api.node.uk/api/v1/models` returns
the live model catalogue and needs no authentication.

## Machine-readable discovery

- Agents hub: <https://node.uk/agents/>
- API catalog (RFC 9727): <https://node.uk/.well-known/api-catalog>
- Protected resource metadata (RFC 9728):
  - <https://api.node.uk/.well-known/oauth-protected-resource>
    (`resource` = `https://api.node.uk`)
  - <https://node.uk/.well-known/oauth-protected-resource>
    (`resource` = `https://node.uk`; same auth servers/scopes)
- Authorization server metadata (RFC 8414):
  <https://auth.node.uk/realms/customers/.well-known/oauth-authorization-server>
- MCP (Streamable HTTP): <https://api.node.uk/mcp>
  (server card: <https://node.uk/.well-known/mcp/server-card.json>)
- Service status: <https://status.node.uk/>

## Limits and billing

Each credential has a per-client rate limit (default 100 requests/minute).
Every request is metered per token and lands on your monthly invoice in GBP.
Details: <https://node.uk/ai/ai-gateway/>.