Skip to main content
The Proceeds REST API authenticates with API keys generated from your dashboard. Each key carries a set of scopes that determine which endpoints it can call.

​
Key format

Keys use an mpk_ prefix followed by 64 lowercase hex characters (32 random bytes): 
mpk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
The raw key is shown only once at creation and cannot be recovered later. Store it in a secret manager or environment variable — never in client-side code or version control.

​
Send the key

Provide the key in either header. Both are equivalent: 
curl https://api.myproceeds.xyz/v1/me \
  -H "Authorization: Bearer mpk_your_key_here"

​
Scopes

Each key is granted a set of scopes. Write scopes imply the matching read scope.
ScopeGrants
services:readRead services
services:writeCreate, update, delete services (implies services:read)
paywalls:readRead paywalls
paywalls:writeCreate, update, delete paywalls (implies paywalls:read)
transactions:readRead payment transactions
events:readRead analytics events
A request to an endpoint your key isn’t scoped for returns 403 with code INSUFFICIENT_SCOPE — see Errors & rate limits.

​
Validate a key

Call GET /v1/me with any valid key to confirm it works and inspect the tenant and scopes it carries. No specific scope is required. 
curl https://api.myproceeds.xyz/v1/me \
  -H "X-Api-Key: mpk_your_key_here"
The response returns the associated user, the key’s name and keyPrefix, and its scopes.

​
Secret handling

Secret material is never returned by the API:
  • Service authConfig values (upstream credentials)
  • Paywall custom header values
These are always masked as "***" in responses. The field names are returned so you can see what’s configured, but the plaintext values are not recoverable through the API.

Errors & rate limits

What an auth failure looks like, plus the per-key rate limit.