# auth.md: 1gwei.dev Agent Authentication & Registration

This document specifies how autonomous AI agents, multi-agent frameworks, and developer clients discover, register, claim, and authenticate with the 1gwei.dev API (`https://1gwei.dev/api`).

---

## 1. Discover

Agents discover authentication capabilities and metadata via RFC 9728 Protected Resource Metadata (PRM) and RFC 8414 Authorization Server (AS) metadata:

- **Protected Resource Metadata**: [https://1gwei.dev/.well-known/oauth-protected-resource](https://1gwei.dev/.well-known/oauth-protected-resource)
- **Authorization Server Metadata**: [https://1gwei.dev/.well-known/oauth-authorization-server](https://1gwei.dev/.well-known/oauth-authorization-server)
- **Agent Auth Manifest Anchor**: The AS metadata advertises the `agent_auth` block pointing to this specification.

When calling any protected API endpoint without valid credentials, the server returns an HTTP 401 response carrying the `WWW-Authenticate` header:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://1gwei.dev/.well-known/oauth-protected-resource"
```

---

## 2. Pick a Method

1gwei.dev is a non-KYC crypto gas dispensary supporting three authentication methods for agents:

1. **Anonymous Agent Registration (`anonymous`)**: Instant token provisioning via `register_uri` for ephemeral, non-KYC automation. Includes `claim_uri` to bind sessions if elevated account scopes are ever requested.
2. **Identity Assertion (`identity_assertion`)**: Cryptographically verified agent identity supporting `verified_email` or JSON Web Signature (`urn:ietf:params:oauth:token-type:id-jag`). Uses `claim_uri`.
3. **Permissionless Direct Execution**: Invocations can bypass token registration entirely by funding orders via Lightning Network or Monero.

---

## 3. Register

Autonomous agents can dynamically obtain credentials by calling the `register_uri`:

```http
POST https://1gwei.dev/api/agent/register
Content-Type: application/json

{
  "client_name": "Autonomous Gas Top-up Agent",
  "identity_type": "anonymous"
}
```

Response:
```json
{
  "status": "registered",
  "token_type": "Bearer",
  "access_token": "ag_live_1gwei_ephemeral",
  "expires_in": 86400,
  "scope": "gas:buy gas:quote referral:read",
  "claim_uri": "https://1gwei.dev/api/agent/claim",
  "revocation_uri": "https://1gwei.dev/api/agent/revoke"
}
```

---

## 4. Claim

When an anonymous agent needs to bind its session or register a verified claim, it invokes the `claim_uri`:

```http
POST https://1gwei.dev/api/agent/claim
Content-Type: application/json
Authorization: Bearer ag_live_1gwei_ephemeral

{
  "claim_id": "claim_gas_agent_123"
}
```

Response:
```json
{
  "status": "claimed",
  "claim_id": "claim_gas_agent_123",
  "verified": true,
  "bound_at": "2026-09-07T00:00:00.000Z"
}
```

---

## 5. Use the Credential

Include the bearer token in the `Authorization` header of all subsequent API calls:

```http
GET /api/quote?chain=arbitrum&amountEth=0.005 HTTP/1.1
Host: 1gwei.dev
Authorization: Bearer ag_live_1gwei_ephemeral
```

---

## 6. Errors

Standard authentication errors follow RFC 6749 and RFC 9457:

- `401 Unauthorized`: Missing or invalid token. Includes `WWW-Authenticate: Bearer resource_metadata="https://1gwei.dev/.well-known/oauth-protected-resource"`.
- `403 Forbidden`: Insufficient scopes. Check `scopes_supported` in RFC 9728 metadata.
- `429 Too Many Requests`: Rate limit exceeded.

---

## 7. Revocation

To revoke an active credential or terminate an agent session, call the `revocation_uri`:

```http
POST https://1gwei.dev/api/agent/revoke
Content-Type: application/json

{
  "token": "ag_live_1gwei_ephemeral"
}
```

Response:
```json
{
  "status": "revoked",
  "token_revoked": true,
  "revoked_at": "2026-09-07T00:00:00.000Z"
}
```

---

## Agent Auth Specification (Machine-Readable)

```json
{
  "skill": "https://1gwei.dev/auth.md",
  "register_uri": "https://1gwei.dev/api/agent/register",
  "claim_uri": "https://1gwei.dev/api/agent/claim",
  "revocation_uri": "https://1gwei.dev/api/agent/revoke",
  "identity_types_supported": [
    "anonymous",
    "identity_assertion"
  ],
  "anonymous": {
    "credential_types_supported": [
      "token",
      "bearer_token",
      "none",
      "ephemeral_key"
    ],
    "claim_uri": "https://1gwei.dev/api/agent/claim"
  },
  "identity_assertion": {
    "assertion_types_supported": [
      "verified_email",
      "urn:ietf:params:oauth:token-type:id-jag"
    ],
    "credential_types_supported": [
      "token",
      "bearer_token"
    ],
    "claim_uri": "https://1gwei.dev/api/agent/claim"
  },
  "verified_email": {
    "credential_types_supported": [
      "token",
      "bearer_token"
    ],
    "claim_uri": "https://1gwei.dev/api/agent/claim"
  },
  "events_supported": [
    "https://schemas.agent-auth.org/event/revocation"
  ]
}
```

## Related Resources

- OpenAPI Specification: [https://1gwei.dev/openapi.json](https://1gwei.dev/openapi.json)
- RFC 9727 API Catalog: [https://1gwei.dev/.well-known/api-catalog](https://1gwei.dev/.well-known/api-catalog)
- Agent Documentation: [https://1gwei.dev/llms.txt](https://1gwei.dev/llms.txt)