Skip to main content
AgentWeb supports two authentication methods:
  • OAuth 2.0 for MCP clients that support browser authorization and PKCE. Remote and headless clients can complete the flow by relaying the authorization URL and returning the loopback callback URL to the original waiting process.
  • API keys (bearer tokens) for server-to-server REST calls and non-interactive MCP clients that accept an Authorization header.
This page covers both methods.

Generate an API key

1

Open Settings → API Keys

Sign in to app.agentweb.pro, click the gear icon in the sidebar, and select the API Keys tab.
2

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.
3

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....
4

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.
For MCP clients, the key is configured at the connection layer:
For details on connecting Emma to AI clients, see Connect Emma.

Key properties

The Create API Key dialog in the portal collects one field: 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:
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

  1. Generate a new key.
  2. Update your client (Claude Code, OpenClaw, server config) with the new key.
  3. Confirm the new key works.
  4. Revoke the old key.
There is no in-place key rotation — generate-then-revoke is the supported flow.

OAuth 2.0

OAuth-capable MCP clients authenticate through AgentWeb’s browser authorization flow:
  1. The client creates a PKCE verifier and redirects you to https://app.agentweb.pro/oauth/authorize.
  2. You sign in to AgentWeb and review the requested mcp:tools access.
  3. AgentWeb redirects to the client’s registered callback URL with a one-time authorization code.
  4. The client exchanges the code using the retained PKCE verifier and stores the resulting credentials.

Remote and headless clients

A client running remotely may print the authorization URL instead of opening a browser. Keep the original client process running while you authorize the connection. The redirect usually targets a loopback address such as http://127.0.0.1:<port>/callback?code=...&state=.... If your browser is on a different machine, the callback page may fail to load. Copy the complete URL from the browser address bar and return it to the original waiting process using the client’s callback-paste or standard-input mechanism. Do not start another login command before submitting the callback. A new command creates different state and PKCE values, so the previous callback will be rejected. Treat callback URLs as short-lived credentials and do not store them in logs or issue trackers. If the flow expires, restart authorization and use the new URL. See Connect Emma for the complete connection and verification flow.

Troubleshooting

  • 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.
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.
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.
Last modified on September 11, 2026