Documentation
Authentication and security
Every call is authenticated with a Bearer token and passes the same security checks. Lock each key to your own servers with an IP whitelist.
Bearer token
Send your API key in the Authorization header of every request. Keys start with gk_live_ for production and gk_sandbox_ for testing. Calls with either key are checked and charged the same way.
Authorization: Bearer gk_live_xxxxxxxxxxxxxxxx
curl -sS -X GET 'https://grappi.ai/v1/wallet' \ -H "Authorization: Bearer $GRAPPI_API_KEY"
- Create keys in Dashboard → Apps.
- A key is shown only once, when it is created or rotated. We store a hash of it, so we cannot show it again.
- A key in a URL or query string is not accepted.
Security checks on every request
Checks run in this order. The first failure stops the request.
| Check | What must be true | If it fails |
|---|---|---|
| HTTPS | Calls use TLS 1.2 or later. Plain HTTP is redirected, and an API key must never be sent over it. | Redirect or refused |
| Bearer token | The key must exist, be active, and arrive in the Authorization header. | 401 missing_api_key or invalid_api_key |
| IP whitelist | When the key has an IP allowlist, the caller's address must be on it. | 401 invalid_api_key, “ip not allowed” |
| Domain allowlist | When the key has a domain allowlist, the Origin or Referer must match it. | 401 invalid_api_key, “domain not allowed” |
| Rate limit | 60 requests in each 6-second window, per account. | 429 rate_limited |
| Scope | The key must carry the scope the API requires. | 403 insufficient_scope |
| API activation | The API must be switched on for your account. We switch each API on after your payment. | 403 api_not_activated |
| Request format | Every field is validated before anything is charged. | 422 validation_failed |
| Availability | The API must be open for calls on the platform. | 503 api_unavailable |
| Wallet | The call is paid for from your prepaid wallet before it runs. A call that fails on our side or at the data source is refunded; a "no record found" answer is charged. | 402 insufficient_balance |
| Consent | APIs that read personal financial data require a valid consent for that purpose. | 403 consent_required |
| Audit | Every call is written to a tamper-evident log, with its key and result. | Always on |
IP whitelisting
An IP allowlist locks a key to your servers. Even if the key leaks, it does not work from anywhere else. We strongly recommend one on every production key.
- Open Dashboard → Apps and choose your app.
- Click Edit on the key, or use Create API key for a new one.
- Under IP allowlist, add each public IP address your servers call from.
- Save. The change applies immediately.
| Entry | Example | Matches |
|---|---|---|
| Single IPv4 address | 203.0.113.10 | That address only |
| IPv4 range (CIDR) | 203.0.113.0/24 | 203.0.113.0 to 203.0.113.255 |
| Single IPv6 address | 2001:db8::10 | That exact address |
| Empty list | None | Any address |
A call from any other address is refused before anything is charged:
HTTP/1.1 401 Unauthorized
{
"error": {
"code": "invalid_api_key",
"message": "ip not allowed"
}
}- List the address your traffic leaves from: your NAT gateway or load balancer for cloud servers, not the private address of the machine.
- To see your outbound address, run
curl https://api.ipify.orgfrom the server. - If your servers connect over IPv6, add each exact IPv6 address, or force IPv4 in your HTTP client. IPv6 ranges are not supported.
- We use the address that actually connected to us. Setting an
X-Forwarded-Forheader has no effect. - Add the new address before you move servers, then remove the old one.
Domain allowlist
A domain allowlist restricts a key to web requests from your own sites, using the browser's Origin or Referer header. Enter an exact host such as api.acme.com, or a wildcard such as *.acme.com. Include the port if your site uses a non-standard one, for example app.acme.com:8443. Non-browser clients can set these headers themselves, so use it alongside an IP allowlist, not instead of one.
Scopes
Each key carries a list of scopes, and each API requires one, shown on its reference page. For example, kyc:verify allows identity checks and msg:send allows messaging. A key without the required scope gets 403 insufficient_scope.
A scope alone is not enough. Each API must also be activated for your account: subscribe to it in Dashboard → API access, and we switch it on after your payment. Until then a call to it gets 403 api_not_activated, and nothing is charged.
Rotating and revoking keys
- Rotate issues a new key with the same scopes and allowlists. The old key stops working immediately, so deploy the new one straight away.
- Revoke disables a key immediately and permanently.
- The dashboard shows when each key was last used, so you can spot keys that are unused or used unexpectedly.
Rate limits
Each account can make 60 requests in every 6-second window, across all its keys. Beyond that you receive 429 rate_limited. Wait a few seconds and retry, ideally with increasing delays.
Safe retries
Add an Idempotency-Key header with a unique value to any write. Once a call has finished, retrying it with the same key and body within 24 hours returns the original response without running or charging again. The same key with a different body returns 409 idempotency_key_reused. A retry sent while the first attempt is still running counts as a new call, so wait for a response or timeout first. Use a new key for each file you upload.
Idempotency-Key: 7f3c9a52-1b7e-4d0e-9a51-2c4f0b6e8d11
Go-live security checklist
- Keep the API key on your server, in an environment variable or secret manager.
- Never put a key in a browser, a mobile app, a URL or a code repository.
- Add your servers' public IPs to the IP allowlist before going live.
- Give each key only the scopes it needs, and use a separate key per application.
- Use a live key in production and a separate test key everywhere else.
- Rotate keys on a schedule, and immediately if one may have been exposed.
- Log request_id with each call, and never log the key.
- Collect and store the person's consent before calling an API that requires it.
All error codes are in the error reference. To report a vulnerability, write to support@grappi.ai.