⬡ Nodal Docs

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:

HTTP
POST /checkout/sessions HTTP/1.1
Host: api.tfolanodal.com
Authorization: Bearer np_live_3f9a…
Content-Type: application/json
Idempotency-Key: checkout-order_1042

Keys 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:

AreaEndpoints
Hosted checkoutCreate, get and cancel sessions
CollectionsCreate, list and get
MandatesCreate, list, get, list a mandate's collections, pause, resume, cancel, re-authorise
Payment linksCreate, list, deactivate
Payouts and refundsRequest, 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:

403 Forbidden
{
  "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.