OAuth and rate limits

All PumpCrate agent tools are open, so authentication is optional. Its only purpose is to remove the anonymous rate limit for agents that make many calls.

When you need it#

Anonymous callers can make 60 MCP calls per minute per IP. If your agent stays under that, skip this page. If it needs more, register a client and send a bearer token.

Scopes#

1. Register a client#

There are no end-user accounts, so there is no consent screen. Register with RFC 7591 dynamic client registration:

POST https://www.pumpcrate.com/oauth/register
Content-Type: application/json

{
  "client_name": "Your agent",
  "grant_types": ["client_credentials", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_post"
}

The response contains a client_id and, unless you registered with "token_endpoint_auth_method": "none", a client_secret. Store both; the secret cannot be recovered.

2. Get an access token#

POST https://www.pumpcrate.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=read:site

The response carries access_token, token_type: "Bearer", expires_in of 3600 seconds and the granted scope. Send it on MCP calls:

Authorization: Bearer <access_token>

3. Refresh and revoke#

• Requesting offline_access also returns a refresh_token. It is single use: exchange it at the token endpoint with grant_type=refresh_token for a new access token and a new refresh token.
• Refresh tokens live for 30 days.
• POST https://www.pumpcrate.com/oauth/revoke with token=<refresh token> discards a refresh token.

Verifying tokens#

Access tokens are RS256 JWTs. The issuer (iss) is https://www.pumpcrate.com and the audience (aud) is https://www.pumpcrate.com/mcp.

Rate limit responses#

When an anonymous caller goes over the limit, the response is HTTP 429 with JSON-RPC error -32001, a Retry-After header with the seconds to wait, and a WWW-Authenticate header pointing to the protected resource metadata. A well-behaved client waits for Retry-After, or registers and retries with a token.