> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, rate limits, and how requests are authenticated.

![API key authenticates requests to the AgentMall server](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/authentication.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=0551e54bb574eced057f3c27e9444da1)

Every request needs an API key. There is no anonymous access.

## Sending the key

```http theme={null}
Authorization: Bearer <api-key>
```

MCP also accepts `?key=` on the server URL. Prefer the header so the key stays out of logs and shared configs.

```text theme={null}
https://mcp.getagentmall.com?key=YOUR_KEY
```

Your key belongs to your organization. Do not commit it, paste it into shared chats, or embed it in a client-side app.

## Key types

| Prefix | Mode | Behavior |
| - | - | - |
| `am_live_` | Live | Full flow. Orders are submitted to the merchant. A fee is charged per confirmed order. |
| `am_test_` | Test | Full flow. The review is read and verified, but nothing is submitted to the merchant. Orders are stored with `test: true`. No fee. |

Test keys run the same code path as live keys — address validation, review hash checking, and totals verification all happen. The only difference is that `complete_checkout` does not submit to the merchant.

## Getting a key

Mint a key in the [console](https://console.getagentmall.com/keys), or use the one from your welcome email. The key is shown once at creation. The same page shows today's search usage against your daily cap.

## Request rate

Each key can make 15 requests per second, across MCP and REST together. Every MCP message and every REST call counts, not only searches.

When exceeded:

| Field | Value |
| - | - |
| HTTP status | `429` |
| Error code | `rate_limited` |
| Body | `retry_after_seconds` — wait this long before the next request |

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Wait and retry.",
    "retry_after_seconds": 1
  }
}
```

Need more? Reply to your welcome email.

## Daily search cap

`search_catalog` counts against a per-key daily allowance. The day resets at UTC midnight.

When the cap is hit:

| Code | Meaning |
| - | - |
| `daily_limit_reached` | Today's searches are used up. The response includes `used_today` and `daily_cap` (MCP) or `usedToday` and `dailyCap` (REST). |

Non-search tools do not consume the allowance. Failed searches that return `invalid_key`, `unauthorized`, `invalid_arguments`, `rate_limited`, or `daily_limit_reached` are not counted.

Need a higher cap? Reply to your welcome email.

## Auth errors

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `unauthorized` | 401 | No key on the request | Add `Authorization: Bearer <key>` |
| `invalid_key` | 401 | Key not recognized | Check the key, or ask the AgentMall team for a beta key |

A key that was sent but is wrong, revoked, or mistyped is always `invalid_key`, never `unauthorized`.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "API key required. Send Authorization: Bearer <key>."
  }
}
```

```json theme={null}
{
  "error": {
    "code": "invalid_key",
    "message": "API key not recognised. Check the key, or ask the AgentMall team for a beta key."
  }
}
```

## Surfaces

| Surface | Auth |
| - | - |
| MCP `mcp.getagentmall.com` | Bearer (or `?key=`) on every tool call |
| REST `api.getagentmall.com/v1/*` | Bearer on every route except `GET /health` |
| Console `console.getagentmall.com` | Sign-in session. Pages show that organization's data only. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.