# auth.md

How an autonomous agent obtains credentials for the Nyas API.

Nyas is the developer cloud for modern applications and AI agents. This
document tells an agent how to authenticate before calling the REST API at
`https://api.nyas.io` or the MCP endpoint at `https://api.nyas.io/mcp`.

## Agent audience

This document is for software agents acting **on behalf of an existing Nyas
user**. Nyas does not currently issue credentials to unattended agents that
have no human account behind them — see [Self-registration](#self-registration)
below. An agent authenticated this way inherits the permissions of the user
who approved it, scoped down to the scopes it requested.

## Discovery

| Document | URL |
| --- | --- |
| Protected resource metadata | `https://nyas.io/.well-known/oauth-protected-resource` |
| Authorization server metadata | `https://app.nyas.io/.well-known/oauth-authorization-server` |
| MCP server card | `https://nyas.io/.well-known/mcp/server-card.json` |

The protected resource metadata advertises a single authorization server,
`https://app.nyas.io`. Read the authorization server metadata from that host
rather than from `nyas.io`; the issuer there is authoritative.

## Registration

Nyas has no programmatic client-registration endpoint. There is no
`POST /agent/auth`, and no OAuth Dynamic Client Registration (RFC 7591)
support. Do not probe for one.

Agents authenticate as a **public client with no client secret**
(`token_endpoint_auth_methods_supported: ["none"]`), so no registration step
is required. Pick a stable, descriptive `client_id` that identifies your agent
to the user approving it — it is shown on the approval screen.

## Supported method: OAuth 2.0 Device Authorization Grant

The device authorization grant (RFC 8628) is the only grant Nyas supports. It
suits agents because it never requires the agent to handle a redirect URI, run
a web server, or see the user's password.

**1. Request a device code.**

```http
POST /oauth/device_authorization HTTP/1.1
Host: app.nyas.io
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_AGENT_ID&scope=database%3Aread%20database%3Awrite
```

The response contains `device_code`, `user_code`, `verification_uri`,
`expires_in`, and `interval`.

**2. Present the code to the user.** Show `user_code` and `verification_uri`
and ask them to visit it in a browser. This is the point where a human
authorizes your agent; it cannot be automated away.

**3. Poll the token endpoint** at `interval` seconds, no faster:

```http
POST /oauth/token HTTP/1.1
Host: app.nyas.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
&device_code=DEVICE_CODE&client_id=YOUR_AGENT_ID
```

Until the user approves, this returns `authorization_pending` — keep polling.
On `slow_down`, increase your interval. On `expired_token` or `access_denied`,
stop and start over; do not retry in a tight loop.

## Scopes

| Scope | Grants |
| --- | --- |
| `database:read` | Read database metadata and run read-only SQL |
| `database:write` | Run mutating SQL and manage database contents |
| `database:admin` | Provision, resize, and delete database instances |

Request the narrowest set that does the job. `database:admin` can destroy
data and should not be requested by an agent that only needs to query.

## Using the credential

Send the access token as a bearer token in the `Authorization` header — the
only method advertised in `bearer_methods_supported`:

```http
GET /v1/databases HTTP/1.1
Host: api.nyas.io
Authorization: Bearer ACCESS_TOKEN
```

Do not put the token in a query string or a cookie. Treat it as a secret:
keep it out of logs, prompts, and any context you send to a third party.

On `401 Unauthorized`, the token has expired or been revoked — restart the
device flow rather than retrying the same token.

## Revocation

Tokens are revoked by the user from the Nyas dashboard at
`https://app.nyas.io`. There is no programmatic revocation endpoint
(RFC 7009) yet, so an agent cannot revoke its own credential via the API.
If you believe a token has leaked, tell the user to revoke it in the
dashboard.

## Self-registration

Nyas does not support agent self-registration today. There is no anonymous
identity flow, no verified-email claim flow, and no ID-JAG identity assertion
exchange. The Authentication service is in development; when it ships, this
document and the `agent_auth` block in the authorization server metadata will
describe the registration endpoint and the identity and credential types it
accepts.

Until then, an agent that has no user to authorize it cannot obtain Nyas
credentials.

## Contact

Docs: <https://app.nyas.io/docs> · Support: <mailto:support@nyas.io>