Authentication
PowaAgent accepts two kinds of credential:
| Credential | Use it for | How to get it |
|---|---|---|
| API key | Local agents and clients, and direct calls to the PowaAgent API | Create one under API key in the portal. See API keys. |
| OAuth sign-in | Hosted assistants (Claude, ChatGPT, Grok) connecting to the PowaAgent connector | Sign in to PowaAgent when your assistant asks |
API keys
Send your key as a bearer token on every request:
Authorization: Bearer <your PowaAgent API key>
- A key is a long opaque string. Copy it exactly as shown when you created it.
- Each key has an expiry date that you choose when you create it, up to 365 days.
- Your account can have one active key at a time. To replace it, revoke it and create a new one.
- There's no separate test key. You choose the sandbox per request. See Sandbox testing.
An API key can call:
| Endpoint | Purpose |
|---|---|
https://mcp.powaagent.ai/mcp | The PowaAgent connector (MCP) |
POST https://api.powaagent.ai/wallets/signatures | Sign a payment |
POST https://api.powaagent.ai/wallets/testnet/funds | Request test USDC for the sandbox |
GET https://api.powaagent.ai/buyers/catalog | Read the catalog. This one also works without a key. |
An API key can't change your account settings, source policy or keys. Those changes are made in the portal.
OAuth for the connector
The PowaAgent connector at https://mcp.powaagent.ai/mcp supports OAuth sign-in for hosted assistants. If a client connects without a key, the server replies 401 with a challenge pointing to its OAuth metadata:
WWW-Authenticate: Bearer resource_metadata="https://mcp.powaagent.ai/.well-known/oauth-protected-resource", scope="https://mcp.powaagent.ai/mcp/access"
Clients that support MCP OAuth follow this automatically. You sign in to PowaAgent at auth.powaagent.ai and approve access. Sign-in requires your password and your authenticator code.
OAuth sign-in needs a client that receives the sign-in result at an https:// web address. Clients that run on your own machine and expect a localhost address should use an API key instead.
When authentication fails
A missing, invalid, expired or revoked credential is rejected with:
HTTP/1.1 401 Unauthorized
{"message":"Unauthorized"}
The response doesn't say which of these it was. Check that:
- The header is exactly
Authorization: Bearer <key>. - The key is shown as active on the API key page and hasn't expired.
- You're calling one of the endpoints listed above.
Keep credentials safe
Anyone with your API key can spend from your wallet, within your source policy. Keep keys out of source control, set spend caps, and revoke a key straight away if it may have been exposed.