# auth.md

How an AI agent obtains credentials for Everruns.

Everruns is a durable agent platform. This document describes how an agent
authenticates to **Everruns Cloud** (`https://app.everruns.com`), the managed
edition. A self-hosted Everruns server exposes the same endpoints on its own
origin, so substitute your origin throughout.

`https://everruns.com` itself is a static marketing site. It hosts no
protected resources and issues no credentials.

## Audience

AI agents and MCP clients that want to create and run Everruns agents, open
sessions, and stream events on behalf of a human account holder.

Everruns does not support anonymous access. Every credential below is bound to
a human-owned account. Account creation is self-service: a human signs up at `https://app.everruns.com` with an email and
password or a Google account, federated through
`https://id.everruns.com`.

## Method 1: MCP over OAuth 2.1 (preferred for agents)

Everruns Cloud exposes a Model Context Protocol endpoint that supports OAuth
dynamic client registration, so an agent can register itself without a human
pre-provisioning a client.

| Field | Value |
| --- | --- |
| MCP endpoint (resource) | `https://app.everruns.com/mcp` |
| Protected resource metadata | `https://app.everruns.com/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `https://app.everruns.com/.well-known/oauth-authorization-server` |
| Issuer | `https://app.everruns.com` |
| Registration endpoint (RFC 7591) | `https://app.everruns.com/oauth/register` |
| Authorization endpoint | `https://app.everruns.com/oauth/authorize` |
| Token endpoint | `https://app.everruns.com/oauth/token` |
| Grant types | `authorization_code`, `refresh_token` |
| PKCE | required, `S256` |
| Scopes | `mcp` |
| Credential presentation | `Authorization: Bearer <access_token>` |

Flow:

1. Fetch the protected resource metadata to discover the authorization server.
2. Fetch the authorization server metadata for live endpoints. Do not hardcode
   the table above; treat it as documentation and the metadata as truth.
3. Register a client at the registration endpoint.
4. Run the authorization code flow with PKCE. A human approves the grant in a
   browser.
5. Call the MCP endpoint with the access token in the `Authorization` header.

```json
{
  "agent_auth": {
    "skill": "everruns-mcp",
    "register_uri": "https://app.everruns.com/oauth/register",
    "methods": [
      {
        "type": "oauth2",
        "resource": "https://app.everruns.com/mcp",
        "issuer": "https://app.everruns.com",
        "authorization_endpoint": "https://app.everruns.com/oauth/authorize",
        "token_endpoint": "https://app.everruns.com/oauth/token",
        "registration_endpoint": "https://app.everruns.com/oauth/register",
        "grant_types_supported": ["authorization_code", "refresh_token"],
        "code_challenge_methods_supported": ["S256"],
        "scopes_supported": ["mcp"],
        "bearer_methods_supported": ["header"]
      }
    ]
  }
}
```

## Method 2: Personal access token (REST API)

For server-to-server use where no browser is available, a human issues a
personal access token from the Everruns operator console, under
**Settings → Personal access tokens**, and hands it to the agent out of band.

| Field | Value |
| --- | --- |
| API base | `https://app.everruns.com/api` |
| Token format | opaque string prefixed `evr_pat_` |
| Credential presentation | `Authorization: Bearer evr_pat_...` |
| OpenAPI description | <https://everruns.com/docs/api/> |

```bash
curl -X POST https://app.everruns.com/api/v1/agents \
  -H "Authorization: Bearer $EVERRUNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Assistant","system_prompt":"You are helpful."}'
```

A personal access token carries the full authority of the account that issued
it. Store it as a secret, never in source control, and rotate it from the same
screen that issued it.

## Credential handling

- Send credentials only over TLS, and only to the origin that issued them.
- Present tokens in the `Authorization` header. Do not place them in query
  strings, where they leak into logs and referrers.
- Access tokens are short-lived. Refresh them rather than re-running the
  authorization flow.
- If a request returns `401`, re-read the protected resource metadata before
  retrying: endpoints and scopes can change.

For MCP setup and platform workflows, use the shared
[everruns-mcp skill](https://everruns.com/.well-known/agent-skills/everruns-mcp/SKILL.md).

## Related discovery documents

- <https://everruns.com/.well-known/api-catalog> — linkset of Everruns APIs
- <https://everruns.com/.well-known/ai-catalog.json> — ARD capability manifest
- <https://everruns.com/llms.txt> — site index for LLMs
- <https://everruns.com/docs/> — full documentation

## Contact

Security or access questions: <contact@everruns.com>