# Authenticating with UnaGo

This document explains how an autonomous agent obtains credentials and calls the
UnaGo platform API and MCP gateway. All endpoints below are the real,
operator-configured endpoints — discover them programmatically from the linked
`.well-known` documents rather than hard-coding them.

## Discovery documents

- OAuth protected resource (RFC 9728): [https://unago.ai/.well-known/oauth-protected-resource](https://unago.ai/.well-known/oauth-protected-resource)
- OAuth authorization server (RFC 8414, includes the `agent_auth` block): [https://unago.ai/.well-known/oauth-authorization-server](https://unago.ai/.well-known/oauth-authorization-server)
- OpenID Connect discovery (302 → the authorization server): [https://unago.ai/.well-known/openid-configuration](https://unago.ai/.well-known/openid-configuration)
- MCP server card (SEP-1649): [https://unago.ai/.well-known/mcp/server-card.json](https://unago.ai/.well-known/mcp/server-card.json)
- API catalog (RFC 9727 linkset): [https://unago.ai/.well-known/api-catalog](https://unago.ai/.well-known/api-catalog)

## What is protected

| Resource | URL |
| --- | --- |
| Platform API base | https://platform.unago.ai |
| MCP gateway (streamable-http) | https://platform.unago.ai/hyperion-core/mcp |

The authorization server protecting these resources is **https://auth.unago.ai**
(OpenID Connect / OAuth 2.0).

## Authorization server endpoints

These are published by the authorization server itself; the values below are
derived from its issuer and are confirmed by its discovery document.

| Endpoint | URL |
| --- | --- |
| Issuer | https://auth.unago.ai |
| OIDC discovery | https://auth.unago.ai/.well-known/openid-configuration |
| Authorization | https://auth.unago.ai/oauth/v2/authorize |
| Token | https://auth.unago.ai/oauth/v2/token |
| JWKS | https://auth.unago.ai/oauth/v2/keys |
| UserInfo | https://auth.unago.ai/oidc/v1/userinfo |

> The authoritative `registration_endpoint` (RFC 7591 Dynamic Client
> Registration) is published in the OIDC discovery document above. Resolve it
> from there rather than assuming a path.

## How an agent gets credentials

### Option A — Human-delegated access (Authorization Code + PKCE)

1. Create or sign in to an account at [https://platform.unago.ai/signup](https://platform.unago.ai/signup).
2. Register an OAuth client (use the `registration_endpoint` from the OIDC
   discovery document, or an operator-provisioned client).
3. Run the OAuth 2.0 Authorization Code flow **with PKCE (S256)** against the
   authorization endpoint, then exchange the code at the token endpoint.
4. Request the scopes you need: `openid profile email offline_access`.

### Option B — Service account (non-interactive)

For unattended agents, use a service-account credential (e.g. a Personal Access
Token issued by the authorization server / platform admin). Present it as a
bearer token — there is no separate password exchange.

## Calling the API and MCP gateway

Send the access token in the `Authorization` header on every request:

```http
Authorization: Bearer <access_token>
```

- REST API: `https://platform.unago.ai`
- MCP (streamable-http): `https://platform.unago.ai/hyperion-core/mcp` — perform the MCP `initialize` handshake,
  then `tools/list` and `tools/call`.

If a request is unauthenticated, the resource responds `401` with a
`WWW-Authenticate` challenge pointing back at the protected-resource metadata
above, so you can (re)discover the correct authorization server.

## Identity & credential types

- **Identity types:** `human-delegated`, `service-account`
- **Credential types:** `oauth2-bearer`, `personal-access-token`