Authentication
Authenticate your requests with your API key in the Authorization header. Use a private key for sensitive operations, a public key for the rest.
The API uses key-based (token) authentication. You pass your key in the Authorization
header of each request. Wajub accepts the key directly, without the Bearer prefix.
Private keys (sk...) grant access to all operations; public keys (pk...)
are limited to non-sensitive operations (payment initialization, reading public resources);
restricted keys (rk...) grant access to only the specific resources you scope them to.
https://api.wajub.com/balanceThe three-key model
AuthorizationheaderrequiredThree key types
Secret keys are unrestricted and must never leave your server. Public keys are safe to
expose client-side but limited to non-sensitive operations. Restricted keys let you issue a
key scoped to a subset of resources (e.g. payment.read only) for a specific integration or third
party — create and scope them from Developers → API Keys.
Official server SDKs
Wajub ships official server SDKs for Node.js, Python, PHP, Go, Ruby, Java, and C#. See SDKs & Libraries.
curl https://api.wajub.com/balance \
-H "Authorization: sk_test.2a7c5e91b0d34f68"Authentication errors
{
"code": 401,
"status": "Unauthorized",
"message": "Invalid API credentials"
}A key that was valid but has since expired returns the same 401 with
"message": "Invalid or revoked API credentials" instead.
401— key missing, malformed, expired or revoked.403— the key doesn't have the required permission for the requested operation, the request came from an IP address not on that key's allow-list ("message": "IP address not allowed for this API key"), or a private key was used from a browser (see below).
Protect the private key
Never include sk… in client-side code (browser, mobile). In case of a leak, revoke the
key from Developers → API Keys: rotation is instant and does not affect your other
keys.
As a safety net, Wajub also detects this automatically: any request authenticated with a
private key (sk... / sk_test...) that carries an Origin or Referer header — the
signature of a call made from a browser rather than your server — is rejected with:
{
"code": 403,
"status": "Forbidden",
"message": "Security Alert: You are trying to use a Private Key from a browser/frontend. Private keys must ONLY be used in server-side code. Please use a Public Key for frontend requests.",
"documentation_url": "https://docs.wajub.com/api/authentication#authentication-errors"
}The team owner and admins are emailed an alert the first time this happens for a given key
(throttled to one email per key per hour). If you see this error unexpectedly, check for a
private key accidentally bundled into frontend code, and switch that call to a public key
(pk...) or move it server-side.
Best practices
- Store keys in environment variables, never in the repository.
- Use separate keys per environment (test vs production).
- Rotate your keys periodically and after any team member departs.