Authentication

Wajub authenticates with an API key sent raw in the Authorization header. There is no Bearer prefix, no OAuth dance, no signing step.

Authorization: sk_test.xxxxxxxxxxxxxxxx...
Content-Type: application/json

Anatomy of a key

A key is a prefix, a dot, then a random secret. The prefix is the part you read:

sk_test . xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
└──┬──┘   └──────────────────┬──────────────────┘
 │                         └─ random secret, shown once at creation
 └─ type (sk/pk/rk) and environment (_test or nothing)

The prefix carries two facts at once: the key's type, and its environment.

The three key types

Private (sk.) grants every operation and must never leave your server. Restricted (rk.) is a private key narrowed to an explicit list of scopes, for a third party or a single integration. Public (pk.) is the key you ship to a browser or a mobile app to create a payment, and it reaches only what a checkout needs:

• creating a payment (POST /payments), charging it or one of its instalments and finishing the payer's step (POST /payments/{id}, /splits and /confirm), and reading it by id (GET /payments/{id});
• the ways to pay (GET /payments/options), and creating a customer (POST /customers);
• the reference data: GET /, /channels, /countries, /currencies and /providers.

Every other route refuses it with 406 Private Key Required: listing payments, cancelling, activating, updating or closing one and listing its refunds; listing, reading or changing customers; links and invoices; and anything that moves money out, reads your balance or manages your account, a customer's tax_ids included. In sandbox, links and invoices, being live only, answer 403 first. Whoever reads your page can use what a public key reaches, so holding it is not a permission: never use it as access control.

What a public key reads back is narrowed the same way. On POST /payments, customer, shipping_address and billing_address hold only what the request sent, never the customer your account already has with that email or phone. Read with GET /payments/{id}, or returned by POST /payments/{id}, /splits or /confirm, a payment has no customer, shipping_address or billing_address, and its payment_method holds only channel, without account, the payer's number or card. On POST /customers, a customer your account already has with that email or phone comes back as its id and the fields the request sent, never what your account holds. Read them from your server, with a secret or restricted key.

Which endpoints accept which type:

A public key sent to a row marked No is refused before the call does anything:

Restricted key scopes

A restricted key carries a list of resource.action scopes. GET, HEAD and OPTIONS calls need read, everything else needs write. A GET /transfers therefore needs transfer.read, a POST /transfers needs transfer.write.

Two scopes in the list have no writable counterpart. balance.read is read-only because the balance has no write endpoint. /accounts is a different case: creating, updating or deleting a subaccount is a write, and no account.write scope exists yet, so those three calls need a private key. The same applies to /shield, which has no scope at all and is therefore private-key only.

Four paths ignore scopes entirely, because they return the same data for every key on the platform: GET /, /channels, /countries and /currencies.

A scope you did not grant returns a 403 naming exactly what was missing:

Narrowing a key further

Two optional constraints apply to any key type, set when you create it in Settings → Developers → API keys. You can change them later from the same page, on every key type, and editing anything else about the key leaves them as they were. The expiry is shown next to the key.

Authenticating a request

The same call in the five supported stacks. GET /balance needs a private key, which makes it a useful check that your server-side credential is loaded:

curl https://api.wajub.com/balance \
-H "Authorization: $WAJUB_API_KEY"

Or send it straight from this page. Sign in from the top bar first, the request then goes out with your sandbox key:

Authentication errors

Four different failures, all distinguishable by the message:

Private keys are blocked in the browser

Never use a private key (sk. or sk_test.) from a browser or any front-end code. When Wajub detects a private key used from a browser, it refuses the request and alerts you: the secret has reached the front end.

When this happens, the account owner and admins get a security alert by email. If you hit it unexpectedly, look for a private key bundled into front-end code, then either move the call to your server or switch it to a public key.

A restricted key (rk. or rk_test.) belongs on a server too. When Wajub detects one used from a browser, the account owner and admins get the same security alert. For now the request still goes through; Wajub will refuse it with the same 403 later, so move the call to your server now and replace the key.

Practices worth keeping

• Keep keys in environment variables, never in the repository and never in a front-end bundle.
• Use a distinct key per service, not one key shared across your whole estate: a leak or a revocation then touches one service. It buys no throughput: the rate limit is counted for the whole account, whatever key the call carries.
• Give third parties a restricted key with the two or three scopes they actually need.
• Set expires_at on anything temporary: a migration script, an agency's access, a prototype.
• Rotate after anyone with access to your keys leaves.