Authentication

AgentWeb supports two authentication methods:

API keys (bearer tokens) for server-to-server REST calls and MCP from Claude Code or OpenClaw.
OAuth 2.0 for the Claude.ai MCP connector. The connector handles the flow — no manual key generation needed.

This page covers API keys.

Generate an API key

Open Settings → API Keys

Click Create API Key

Give the key a name (something like local-dev, production-server, or cursor-mcp), then click Create Key. The name is the only field the dialog collects.

Copy the key immediately

The full key is shown once. Copy it now. The portal stores only a hash — you cannot view the key again after closing the modal.Keys look like aw_f0dfbe594b4611c5f3e5e411254932a2....

Store it securely

Treat the key like a password. Add it to your secret manager, .env file (gitignored), or your client’s MCP config. Do not commit it to source control.

Use the key

Pass the key in the Authorization header as a bearer token.

curl https://api.agentweb.pro/api/emma/knowledge-bases \
  -H "Authorization: Bearer aw_YOUR_API_KEY_HERE"

For MCP clients, the key is configured at the connection layer:

Claude Code
OpenClaw
Custom MCP client

claude mcp add \
  --transport http \
  emma \
  https://api.agentweb.pro/mcp \
  --header "Authorization: Bearer aw_YOUR_API_KEY_HERE"

openclaw config set agentweb_api_key aw_YOUR_API_KEY_HERE

Add the Authorization: Bearer ... header to the HTTP transport when connecting to https://api.agentweb.pro/mcp.

For details on connecting Emma to AI clients, see Connect Emma.

Key properties

The Create API Key dialog in the portal collects one field:

Property	Description
`keyName`	A label for your reference. Shows up in the key list. Required.

The following properties exist on the key record but have no control in the portal. You can set them only by calling POST /api/v1/agent/api-keys directly:

Property	Description
`scopes`	Recorded on the key and returned by the API, but not enforced. Defaults to `["tools:read", "tools:execute"]`.
`rateLimitPerMin`	Per-key request limit for MCP requests, applied over a rolling 60-second window. Defaults to `60`.
`expiresAt`	Optional expiration timestamp. Once it has passed, the key is rejected.

Scopes are not a permission boundary. AgentWeb stores the scopes array on the key and returns it from the API, but no code path reads it when deciding whether to serve a request. A key created with narrow scopes — or with an empty array — has exactly the same access as any other key on your account. Do not use scopes to restrict what a key can reach. Treat every API key as full access to your account, and limit exposure by issuing separate keys per client and revoking the ones you no longer need.

List your keys

Settings → API Keys lists your keys with the name, an active/revoked status badge, the masked key (aw_... plus the last six characters), the creation date, and the last-used date once the key has been used. Revoked keys stay in the list with a revoked badge. Scopes and rate limits are not shown. Hashes are stored, not the full keys.

Revoke a key

Click Revoke next to the key. Revocation is immediate — the next request with that key returns 401 Unauthorized. Revoke a key any time you suspect it’s leaked, when a team member leaves, or when you’re rotating credentials.

Rotate a key

Generate a new key.
Update your client (Claude Code, OpenClaw, server config) with the new key.
Confirm the new key works.
Revoke the old key.

There is no in-place key rotation — generate-then-revoke is the supported flow.

OAuth 2.0 (Claude.ai)

The Claude.ai connector authenticates via OAuth. The flow:

Claude.ai redirects to https://app.agentweb.pro/oauth/authorize with PKCE parameters.
You sign in to AgentWeb and review the scopes being granted (mcp:tools).
After authorization, Claude.ai exchanges the auth code for an access token and uses it for all subsequent MCP calls.

You don’t generate or manage keys for this path. To revoke the connector, disconnect it from Claude.ai’s Settings → Connectors page or sign out the linked AgentWeb session.

Troubleshooting

401 Unauthorized on every request

Confirm the Authorization header is exactly Bearer aw_... with a space after Bearer.
Confirm the key hasn’t been revoked or expired. Check Settings → API Keys.

429 Too Many Requests

You’ve hit the per-key rate limit — 60 requests per minute by default, measured over a rolling 60-second window. The JSON response body includes retryAfterMs; wait that long before retrying. The portal cannot change a key’s limit, so raising it means creating a new key with rateLimitPerMin through POST /api/v1/agent/api-keys.

The key I just generated isn't working

Some MCP clients cache server configurations. Restart the client after registering a new key. For Claude Code: claude mcp remove emma, then run the add command again.

Next steps

Emma tools — what each endpoint does.
Connect Emma to use the key in Claude.ai, Claude Code, Codex, or OpenClaw.

Introduction

Reference

Authentication

Generate an API key

Use the key

Key properties

List your keys

Revoke a key

Rotate a key

OAuth 2.0 (Claude.ai)

Troubleshooting

Next steps

​Generate an API key

​Use the key

​Key properties

​List your keys

​Revoke a key

​Rotate a key

​OAuth 2.0 (Claude.ai)

​Troubleshooting

​Next steps

Generate an API key

Use the key

Key properties

List your keys

Revoke a key

Rotate a key

OAuth 2.0 (Claude.ai)

Troubleshooting

Next steps