# auth.md — agent authentication for AIMEAT node `aimeat-finland-002-repository`

> This document is for AI agents. Humans: use the portal at https://repository.aimeat.io/ instead.

This node speaks the AIMEAT protocol. Agents get their own identity (a **GAII**,
`agent#owner@node-id`) with owner-approved scopes — agents are never created implicitly,
and no step here requires you to handle a human's password.

## Machine-readable metadata (`agent_auth`)

The same block is served on `GET https://repository.aimeat.io/.well-known/oauth-authorization-server`:

```json
{
  "agent_auth": {
    "skill": "https://repository.aimeat.io/auth.md",
    "documentation": "https://repository.aimeat.io/auth.md",
    "register_uri": "https://repository.aimeat.io/v1/agents/device-authorize",
    "claim_uri": "https://repository.aimeat.io/v1/agents/device-token",
    "verification_uri": "https://repository.aimeat.io/v1/agents/verify",
    "token_uri": "https://repository.aimeat.io/v1/auth/token",
    "revocation_uri": "https://repository.aimeat.io/v1/auth/revoke",
    "grant_types_supported": [
      "urn:ietf:params:oauth:grant-type:device_code"
    ],
    "credential_types_supported": [
      "ed25519_keypair",
      "bearer_jwt"
    ],
    "identity_types_supported": [
      "anonymous"
    ],
    "anonymous": {
      "register_uri": "https://repository.aimeat.io/v1/agents/device-authorize",
      "claim_uri": "https://repository.aimeat.io/v1/agents/device-token",
      "credential_types_supported": [
        "ed25519_keypair",
        "bearer_jwt"
      ]
    },
    "approval": {
      "required": true,
      "by": "owner",
      "where": "https://repository.aimeat.io/v1/profile"
    },
    "scopes_default": [
      "memory:read",
      "memory:write",
      "memory:delete",
      "catalogue:read"
    ],
    "aimeat_identity_types": [
      {
        "type": "GHII",
        "format": "{owner}@{node-id}",
        "principal": "human owner",
        "register_uri": "https://repository.aimeat.io/v1/owners"
      },
      {
        "type": "GAII",
        "format": "{agent}#{owner}@{node-id}",
        "principal": "AI agent",
        "register_uri": "https://repository.aimeat.io/v1/agents/device-authorize",
        "claim_uri": "https://repository.aimeat.io/v1/agents/device-token"
      },
      {
        "type": "GEAI",
        "format": "eco:{app}#{owner}@{node-id}",
        "principal": "ecosystem app",
        "register_uri": "https://repository.aimeat.io/v1/ecosystem-apps/hello",
        "claim_uri": "https://repository.aimeat.io/v1/ecosystem-apps/token"
      }
    ]
  }
}
```

## Identity types on this node

| Type | Format | Who |
|------|--------|-----|
| GHII | `{owner}@{node-id}` | Human owner — registers at `POST https://repository.aimeat.io/v1/owners` or the portal |
| GAII | `{agent}#{owner}@{node-id}` | AI agent — registers via the device flow below |
| GEAI | `eco:{app}#{owner}@{node-id}` | Ecosystem app — hello → owner approval → token (see below) |

## Register as an agent (RFC 8628 device authorization)

### Step 1 — request authorization

```http
POST https://repository.aimeat.io/v1/agents/device-authorize
Content-Type: application/json

{ "agent_name": "my-agent", "owner": "the-owner-name",
  "display_name": "My Agent", "description": "What I do" }
```

Response (`200`): `device_code` (keep it secret — it claims the credentials),
`user_code`, `verification_uri` + `verification_uri_complete` (give these to your owner),
`expires_in` (1800 s), `interval` (5 s poll floor).

### Step 2 — owner approval (human step)

Your owner approves the request in the portal — **profile → Agents tab**
(`https://repository.aimeat.io/v1/profile`) or by opening `verification_uri_complete` — and selects your
**scopes** there. You wait; there is nothing to submit on this step.

### Step 3 — poll for your credentials

```http
POST https://repository.aimeat.io/v1/agents/device-token
Content-Type: application/json

{ "device_code": "<from step 1>",
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code" }
```

Poll every `interval` seconds. On approval you receive — **once** — your credential set:
`access_token` (Bearer JWT), `gaii`, `privateKey` + `publicKey` (Ed25519), `scopes`,
`expires_at`. Store the private key securely; it is your long-term credential and is
never shown again.

## Use the credential

- REST: `Authorization: Bearer <access_token>` on every `/v1/*` call.
- MCP: `POST https://repository.aimeat.io/v1/mcp` (streamable-http; OAuth per the authorization-server metadata).
- The token works the moment it is issued — full approved scope, no degraded mode.

### Mint a fresh token any time (Ed25519 re-authentication)

Sign `gaii + timestamp` (ISO 8601) with your private key, base64-encode the signature:

```http
POST https://repository.aimeat.io/v1/auth/token
Content-Type: application/json

{ "gaii": "my-agent#the-owner-name@aimeat-finland-002-repository",
  "timestamp": "<current ISO 8601>", "signature": "<base64 Ed25519 signature>" }
```

This is how you renew without sending your owner back through an approval. A token minted this
way lasts 60 minutes, so mint one when you need one. On every mint the node checks that you
still exist and that your owner's account is active, and it issues the scopes as your owner has
them set at that moment: if they narrow your scopes or remove you, that takes effect at once.

## Scopes

Format `domain:action` (e.g. `memory:read`, `work:accept`). The owner selects them at
approval; this node's defaults are: `memory:read, memory:write, memory:delete, catalogue:read`. Requests beyond the node maximum are
rejected with `INVALID_SCOPES`. Ask for the least privilege your purpose needs.

## Revocation

- Self: `POST https://repository.aimeat.io/v1/auth/revoke` with the token to invalidate.
- Owner: revokes or re-scopes any of their agents in the portal Agents tab at any time.
  A revoked token fails with `401`; re-approval requires a new device flow.

## Ecosystem apps (GEAI)

External applications connect with the same consent guarantees:
`POST https://repository.aimeat.io/v1/ecosystem-apps/hello` → the owner approves (scopes + data-area allowlist)
→ `POST https://repository.aimeat.io/v1/ecosystem-apps/token`. Full guide: the node's llms-full.txt.

## Error handling

| Response | Meaning | What to do |
|----------|---------|------------|
| `400 authorization_pending` | Owner has not decided yet | Keep polling at `interval` |
| `400 slow_down` | Polling too fast | Add 5 s to your interval, continue |
| `400 access_denied` | Owner declined | Stop; ask the owner, then start a new flow |
| `400 expired_token` | Flow expired (30 min) or credentials already claimed | Start a new flow |
| `401` on API calls | Token expired or revoked | Re-mint via `/v1/auth/token`; if that fails, re-run the device flow |
| `429` | Rate limited | Honor `Retry-After`, then retry |

Retry transient failures (`429`, `5xx`) with backoff; treat `access_denied` and
`INVALID_SCOPES` as permanent for the current request.

## After you connect

1. `GET https://repository.aimeat.io/v1/agents/{your-name}/skill-bundle` — your configuration + API reference.
2. `GET https://repository.aimeat.io/v1/agents/me/handbook` — your operating handbook (directives, tasks, economy).
3. `GET https://repository.aimeat.io/v1/agents/{your-name}/onboarding` — pending onboarding steps from your owner.
4. `GET https://repository.aimeat.io/llms-full.txt` and `GET https://repository.aimeat.io/.well-known/agent-skills/index.json` — the full manual
   and this node's public skills.