Skip to content

Authentication and keys

One bearer key per environment, sent on every request.

Sandbox: test money only. No request moves real money.

Every request carries an API key as a bearer token: Authorization: Bearer nbk_test_.... There are no sessions, no cookies and no signed requests; the key is the credential, so treat it like a password.

What a key looks like

A key is nbk_{test|live}_{key_id}_{secret}{checksum}. The second segment names the environment the key belongs to, and a key never works in the other environment.

The example sends the key and reads back the organisation and the environment it belongs to. Use the same request as a health check when your service starts.

Code for What a key looks like
GET /v1/accountSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: account } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/account',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, account);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Environments

There are two environments, each with its own host, its own keys and its own balance. Nothing crosses between them: an id, a key or a balance of one is unknown to the other.

KeyHost, money and how you get one
Sandbox keynbk_test_https://sandbox-api.nasfampay.com/v1. Test money only. No request moves real money, and no order reaches Telegram or a blockchain. You create it in your dashboard.
Live keynbk_live_https://api.nasfampay.com/v1. Real money: an order spends your real balance. You create it in your dashboard once your business is activated for live.

The sandbox host answers requests with test money only. The live host answers only a live key, which you create once your business is activated for Live: see Complete Live activation.

Getting a key

You create, rotate and revoke keys yourself, in your dashboard under Developers, API keys. A sandbox key needs only an account. A live key can exist only once your business is activated for live; see Complete Live activation.

The contract has no operation that creates, rotates or revokes a key: a key is never made by another key. See Create and manage API keys.

When a key is refused

Every request is checked against the database, and nothing about a key is cached. A revoked key is refused from the next request on; a request already accepted finishes.

  • invalid_api_key: the key is missing, mistyped or revoked. Any failure without a code of its own is this one.
  • key_expired: the key is past its expiry, though its secret is correct.
  • key_environment_mismatch: the key was sent to the other environment's host. It is refused before any lookup.
  • insufficient_scope: the key is not allowed this operation. The contract does not list the scopes a key can hold.
  • product_not_permitted: the key may buy only some products, and the request named another.
  • ip_not_allowed: the key has allowed IP addresses, and this request came from another address. Nothing is read or written. See Allowed IP addresses.

Keeping keys safe

  • Read the key from the environment or a secret store. Never commit it, log it, or send it to a browser or a mobile app.
  • Keep sandbox and live keys in separate configuration, so a test run can never reach a live balance.
  • If a key may have leaked, stop using it at once.

Common mistakes

  • Putting the key in client-side code. A browser or a mobile app can be read by its user, and a browser is refused with browser_request_refused. Call the API from your server only.
  • Sending a key to the wrong host. A nbk_test_ key works on the sandbox host only.
  • Dropping request_id. Every problem carries one, and a Request-Id header. Log it with every failure and quote it when you report one.