Authentication

API keys, key scopes, and the account checks that can refuse an otherwise valid request.

API keys

Every request is authenticated with the Api-Key header.

curl -s https://sandbox.rasto.co/api/customers -H "Api-Key: sk_test_..."

Keys are issued during partner onboarding and shown once. We store only a hash, so a lost key is replaced rather than recovered.

Prefix	Environment	Base URL
`sk_test_`	Sandbox	`https://sandbox.rasto.co`
`sk_live_`	Live	`https://api.rasto.co`

Manage keys from the dashboard: create, rotate with a grace window, and revoke. Rotation and revocation are audit logged. See Environments for how the two hosts differ.

A key must match its host. An sk_test_ key against the live host, or the reverse, is rejected with 401 environment_mismatch, and the message names the base URL to use.

Scopes

Keys are scoped full or read_only. A read-only key can call every GET and no mutation, and a mutation attempt returns 403 read_only_key.

Use read_only keys anywhere you do not strictly need mutations. The one call worth designing around is PATCH /api/virtual_accounts/{va_id}: whoever can repoint a destination controls where all future deposits are delivered.

Why a request can be refused

Beyond a bad key, authentication enforces your account standing.

403 permission_error:

Code	Meaning
`partner_suspended`	Your account is suspended. Contact support
`partner_tos_required`	Your organization's partner terms are not on record yet
`partner_kyb_required`	Your own business verification is not approved yet
`read_only_key`	A read-only key attempted a mutation
`sandbox_only`	A simulation endpoint was called on the live host

401 authentication_error:

Code	Meaning
`missing_api_key`	No `Api-Key` header
`invalid_api_key`	Unknown key
`api_key_revoked`	The key was revoked
`api_key_expired`	The key's grace window after rotation has passed
`environment_mismatch`	Wrong host for this key's prefix

Your own KYB runs through the same verification pipeline as your customers'. Your organization is registered as its own business customer, and its approval is what opens live access. See Going Live.

Dashboard endpoints

/dashboard/* endpoints are not Api-Key authenticated. They use your dashboard session, and they are where tenant-level operations live: signing up, managing keys, and registering wallet keys. A leaked API key therefore cannot read your audit trail or touch your keys.

Transport and limits

HTTPS only.
Rate limited per API key, or per client IP when unauthenticated: 25 requests per second sustained, with a burst allowance of 100. Exceeding it returns 429 rate_limited with a Retry-After header.
Rate limiting happens before idempotency, so a 429 is never stored as a replayable response.
Every response carries a request-id header, echoed inside error envelopes as request_id. Log it, and quote it when contacting support.

Was this page helpful?