Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iterapay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

IteraPay uses two authentication methods: a Bearer token (JWT) for account-level administrative operations, and an API key scoped to a specific merchant for payment operations. Most day-to-day work — creating invoices, listing transactions, initiating withdrawals — uses the API key. The Bearer token is reserved for actions that manage the merchant account itself, like generating a new API key.

​
Bearer token

Your Bearer token is a JSON Web Token (JWT) issued when you log in to IteraPay. Retrieve it from Settings → API access in your account dashboard. Pass the Bearer token in the Authorization header of every request that requires it: 
Authorization: Bearer <your-bearer-token>
Example — check API key info using Bearer auth: 
curl --request GET \
  --url "https://api.iterapay.com/key/info/{merchantID}" \
  --header "Authorization: Bearer <your-bearer-token>"
Bearer tokens expire according to your account’s session policy. If a request returns 401 Unauthorized, your token may have expired — log in again to obtain a fresh one.

​
API key

API keys are scoped to a single merchant and authenticate all payment operations. You generate an API key using your Bearer token, then use it for every subsequent merchant operation. Pass the API key in the X-Api-Key header: 
X-Api-Key: <your-api-key>
Example — create an invoice using API key auth: 
curl --request POST \
  --url "https://api.iterapay.com/merchants/{merchantID}/invoices" \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{"amount": "100.00", "type": "onetime", "description": "Order #1234"}'
Your API key has full access to all payment operations for its merchant. Store it in an environment variable or secrets manager — never hard-code it in source files or commit it to version control. If your key is compromised, revoke it immediately (see below) and generate a replacement.

​
Generating and revoking API keys

All key management endpoints require Bearer token authentication.
Generate a new API key for your merchant. If a key already exists, this replaces it.
curl --request POST \
  --url "https://api.iterapay.com/key/generate/{merchantID}" \
  --header "Authorization: Bearer <your-bearer-token>"
Response:
{
  "key": "ik_live_c9f3e2a1b4d7e6f0a2c5d8e1f4b7a0c3",
  "merchantId": "b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f",
  "createdAt": "2024-01-01T10:00:00Z"
}
IteraPay only returns the full key value at generation time. Store it immediately.

​
Which auth method does each operation require?

OperationBearer tokenAPI key
Generate API key (POST /key/generate/{merchantID})Required—
Get API key info (GET /key/info/{merchantID})Required—
Revoke API key (DELETE /key/revoke/{merchantID})Required—
Create invoice (POST /merchants/{merchantID}/invoices)—Required
List invoices (GET /merchants/{merchantID}/invoices)—Required
Get payment address (GET /public/invoices/...)—Required
List transactions—Required
Create withdrawal—Required
Manage merchant settingsRequired—
Operations listed under Bearer token are typically performed once during initial setup or key rotation. Your production application only needs the API key for ongoing payment operations.

​
Error codes

IteraPay returns errors in RFC 7807 application/problem+json format. The two authentication-related error codes you are most likely to encounter are: 401 Unauthorized — The request did not include a valid credential, or the credential has expired or been revoked. Check that:
  • The Authorization header is present and uses the Bearer <token> format, or
  • The X-Api-Key header is present and contains a valid, active API key.
403 Forbidden — The credential is valid but does not have permission for the requested operation. This typically means you used an API key for an operation that requires a Bearer token, or the Bearer token belongs to an account without access to the specified merchant. Example error response: 
{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Bearer token is missing or invalid."
}

​
Security best practices

  • Rotate API keys regularly — revoke the current key and generate a fresh one on a schedule, or any time a team member with key access leaves.
  • Use environment variables — pass credentials through environment variables rather than embedding them in code.
  • Restrict key access — if your infrastructure supports it, limit which services and IP addresses can send requests using your API key. See IP Whitelist for IteraPay’s built-in allowlist feature.
  • Audit key usage — use GET /key/info/{merchantID} to check lastUsedAt and detect unexpected activity.