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.
// 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.
| Key | Host, money and how you get one |
|---|---|
| Sandbox keynbk_ | https:/. Test money only. No request moves real money, and no order reaches Telegram or a blockchain. You create it in your dashboard. |
| Live keynbk_ | 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 aRequest-Idheader. Log it with every failure and quote it when you report one.
Related guides
- Send your own API order: the key in use, step by step.
- Errors: every code a refusal can carry.
- Read your account: the fields of the account behind a key.
