Authentication
Your server authenticates every request with a secret API key, sent as a bearer token.
Creating a key
In the portal, open Integrationsand create an API key. Only an owner or admin of your Nodal account can create or revoke keys. Give each key a name that says where it is used ("Website production"), and optionally an expiry date.
The full key is shown once, when you create it. Nodal stores only a hash of it and cannot show it again: if you lose it, revoke it and create a new one.
Sending the key
Put the key in the Authorization header of every request:
POST /checkout/sessions HTTP/1.1
Host: api.tfolanodal.com
Authorization: Bearer np_live_3f9a…
Content-Type: application/json
Idempotency-Key: checkout-order_1042Keys look like np_live_ followed by 64 hexadecimal characters. A missing, malformed, revoked or expired key gets 401. The message differs between endpoints (for example "Invalid API key" or "Authentication required"), so check the status code, not the text.
What a key can do
A key belongs to your business, not to the person who created it: it keeps working if they leave, and it acts with a fixed integration role. It can be used on these endpoints only:
| Area | Endpoints |
|---|---|
| Hosted checkout | Create, get and cancel sessions |
| Collections | Create, list and get |
| Mandates | Create, list, get, list a mandate's collections, pause, resume, cancel, re-authorise |
| Payment links | Create, list, deactivate |
| Payouts and refunds | Request, list and get — never approve |
Everything else needs a person signed in to the portal: approving payouts and refunds, managing API keys, webhooks, team members, MTN credentials, reports and exports. Using a key on one of those gets 403:
{
"error": "API keys can't be used for this endpoint",
"message": "This action requires a signed-in user in the Nodal portal."
}Why a key can't release money
Payouts and refunds created with a key wait for a person on your team to approve them in the portal. A leaked key can queue a request, but it can never send money out of your wallet on its own.
Keeping keys safe
- Call the API from your server only. Never put a key in a web page, a mobile app or a public repository.
- Load the key from an environment variable or secret manager, not from source code.
- Use a separate key for each system, so you can revoke one without breaking the others.
- If a key may have leaked, revoke it under Integrations straight away. It stops working on the next request.