- 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
Authorizationheader.
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 theAuthorization header as a bearer token.
- Claude Code
- OpenClaw
- Custom MCP client
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:
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 returns401 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.
OAuth 2.0
OAuth-capable MCP clients authenticate through AgentWeb’s browser authorization flow:- The client creates a PKCE verifier and redirects you to
https://app.agentweb.pro/oauth/authorize. - You sign in to AgentWeb and review the requested
mcp:toolsaccess. - AgentWeb redirects to the client’s registered callback URL with a one-time authorization code.
- 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 ashttp://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
429 Too Many Requests
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
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.

