<!-- Last Modified: 2026-06-13T03:57:10+03:00 -->
# auth.md

You are an agent. This service — **Freed Finance** — supports **agentic registration** via API key provisioning. Follow the steps below to discover how to authenticate, register, and call the Freed Finance API.

## Step 1 — Discover

Discovery uses two endpoints. Start with the Protected Resource Metadata.

### 1a. Fetch the Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
Host: freed.finance
```

Response:

```json
{
  "resource": "https://freed.finance",
  "resource_name": "Freed Finance",
  "resource_logo_uri": "https://freed.finance/web-app-manifest-512x512.png",
  "authorization_servers": ["https://freed.finance"],
  "scopes_supported": ["portfolio", "oracle", "swap", "market", "transfer", "lending", "perps"],
  "bearer_methods_supported": ["header"]
}
```

- `resource` — the canonical URL of the API you are calling.
- `authorization_servers` — base URL of the authorization server.
- `scopes_supported` — scopes your API key will be granted. Default keys receive `portfolio`, `oracle`, `swap`.
- `bearer_methods_supported` — send your API key as `Authorization: Bearer freed_pk_live_…`.

### 1b. Fetch the Authorization Server Metadata

```http
GET /.well-known/oauth-authorization-server
Host: freed.finance
```

Response:

```json
{
  "issuer": "https://freed.finance",
  "authorization_endpoint": "https://freed.finance/api/siwe?action=nonce",
  "token_endpoint": "https://freed.finance/api/auth/api-key",
  "jwks_uri": "https://freed.finance/.well-known/jwks.json",
  "revocation_endpoint": "https://freed.finance/api/auth/api-key",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "read",
    "write",
    "admin",
    "portfolio:read",
    "swap:execute",
    "perps:trade",
    "shield:scan",
    "shield:revoke",
    "agents:manage",
    "mcp:invoke"
  ],
  "response_types_supported": [
    "token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "private_key_jwt"
  ],
  "service_documentation": "https://freed.finance/sdk",
  "agent_auth": {
    "skill": "https://freed.finance/auth.md",
    "register_uri": "https://freed.finance/api/auth/api-key",
    "identity_types_supported": [
      "anonymous"
    ],
    "anonymous": {
      "credential_types_supported": [
        "api_key"
      ],
      "claim_uri": "https://freed.finance/sdk"
    },
    "revocation_uri": "https://freed.finance/api/auth/api-key",
    "events_supported": []
  }
}
```

The response includes standard OAuth fields and the `agent_auth` block describing agent registration.

## Step 2 — Pick a method

Freed Finance supports the following agent registration identity types, which are listed in `agent_auth.identity_types_supported`:

1. **Anonymous** — Register without a user identity. Connect a wallet later to claim full access.

Cross-check against the `agent_auth.identity_types_supported` array in the Authorization Server Metadata.

## Step 3 — Register

### Anonymous registration

No user identity assertion is needed. Create an API key through the Freed Finance web interface or programmatic API.

**Web interface:**

1. Navigate to [https://freed.finance/sdk](https://freed.finance/sdk)
2. Connect your wallet
3. Generate an API key under the Developer section

**Programmatic registration** (requires an active wallet session):

```http
POST /api/auth/api-key
Host: freed.finance
Content-Type: application/json
Cookie: <session-cookie>

{
  "label": "My Agent",
  "env": "live"
}
```

Response (the raw key is returned **once** — save it immediately):

```json
{
  "success": true,
  "data": {
    "key": "freed_pk_live_<32-char-hex>",
    "prefix": "freed_pk_live_",
    "lastFour": "ab12",
    "label": "My Agent",
    "message": "Save this key now — it will not be shown again."
  }
}
```

## Step 4 — Use the API key

Include the key in the `Authorization` header on every API call:

```http
GET /api/portfolio/summary
Host: freed.finance
Authorization: Bearer freed_pk_live_<your-key>
```

### Rate limits

| Tier   | Requests / min |
|--------|---------------|
| Free   | 100           |

### Default scopes

- `portfolio` — Read portfolio balances and positions
- `oracle` — Query price feeds, OHLCV, technical indicators
- `swap` — Execute cross-chain token swaps

## Step 5 — Revoke

To revoke an API key:

```http
DELETE /api/auth/api-key
Host: freed.finance
Content-Type: application/json
Cookie: <session-cookie>

{
  "id": 42
}
```

## API Documentation

- **REST API docs**: [https://freed.finance/sdk](https://freed.finance/sdk)
- **OpenAPI spec**: [https://freed.finance/api/openapi](https://freed.finance/api/openapi)
- **MCP server**: [https://freed.finance/mcp](https://freed.finance/mcp)

## Contact

- Email: [team@freed.finance](mailto:team@freed.finance)
- Discord: [https://discord.gg/uhChTk3C](https://discord.gg/uhChTk3C)
- X: [@freed_finance](https://x.com/freed_finance)