# auth.md — Authenticating with MyApi

MyApi is a personal API gateway. Agents authenticate with a Bearer token and act
within the scopes and usage limits the account owner grants.

## Agent registration

To register as an agent:

1. **Register an account** (or have the account owner invite you):
   `https://www.myapiai.com/signup` (register_uri). Human owners register agents on their behalf.
2. **Choose a registration method / credential type:**
   - **OAuth 2.0 client registration (recommended for AI clients):**
     authorization-code flow with PKCE (S256). Discovery metadata:
     `https://www.myapiai.com/.well-known/oauth-authorization-server`. The user approves your
     client on a consent screen; you receive an access token plus a refresh token.
   - **Bearer token:** the account owner registers your agent by creating a scoped
     token at `https://www.myapiai.com/dashboard/tokens` and giving it to you.
   - **Ed25519 device keypair (MCP):** run `npx myapi-asc-mcp`. It registers an
     Ed25519 keypair against the account as a device credential.
3. **Claim the registration:** device registrations wait in an approval queue; the
   owner claims/approves them at `https://www.myapiai.com/dashboard/devices` (claim URL). Until
   approved, calls return 403.

**Supported identity types:** `user_delegated` (agent acts for a human user) and
`agent` (device-bound agent identity).
**Supported credential types:** `oauth2_authorization_code`, `bearer_token`,
`ed25519_keypair`.

Machine-readable `agent_auth` block (also served in
`/.well-known/oauth-authorization-server`):

```json
{
  "agent_auth": {
    "skill": "https://www.myapiai.com/auth.md",
    "register_uri": "https://www.myapiai.com/signup",
    "identity_endpoint": "https://www.myapiai.com/api/v1/agentic/asc/register",
    "claim_uri": "https://www.myapiai.com/dashboard/devices",
    "claim_endpoint": "https://www.myapiai.com/dashboard/devices",
    "identity_types_supported": ["anonymous", "user_delegated", "agent"],
    "anonymous": { "credential_types_supported": ["ed25519_keypair", "bearer_token"] },
    "credential_types_supported": ["oauth2_authorization_code", "bearer_token", "ed25519_keypair"],
    "registration_methods": ["oauth2_authorization_code", "dashboard_token", "asc_device_key"],
    "revocation_uri": "https://www.myapiai.com/dashboard/tokens"
  }
}
```

## Call the API

```
GET https://www.myapiai.com/api/v1/services
Authorization: Bearer <token>
```

Full spec: `https://www.myapiai.com/openapi.json`. Quick start: `https://www.myapiai.com/api/v1/quick-start`.

## Scopes and limits

Scopes are hierarchical: `full` > `services:*` > `services:{name}:read|write`,
with per-resource sub-scopes on some services. Per-agent daily/monthly usage limits
may apply; exceeding them returns HTTP 429.

## Revocation

Owners revoke agent tokens at `https://www.myapiai.com/dashboard/tokens` (revocation URL) and
device credentials at `https://www.myapiai.com/dashboard/devices`. Revocation is immediate.

## Rules for agents

Before performing ANY action, describe what you intend to do and wait for explicit
human approval. Every request is written to an immutable audit log.