Skip to content

Create and manage API keys

Create, rotate and revoke keys in your dashboard. The API itself never makes a key.

Keys live in your dashboard, under Developers, API keys. A key belongs to one workspace and one environment. The public API has no operation that creates, rotates or revokes one, so a leaked key can never make another.

Create a key

  • Creating or rotating a key needs a sign-in in the last five minutes; if yours is older, the dashboard asks you to sign in again first.
  • Name it after where it is used, such as Staging server, so a key you need to revoke is easy to find.
  • You choose what the key may do when you create it: there is no default and no wildcard. Give it only what the service using it needs.
  • The key is shown once. Copy it straight to your secret store: it cannot be read again.

Store it on your server

  • Keep it in your secret manager, or in an environment variable of the server that calls the API: NASFAM_SANDBOX_KEY for a sandbox key, NASFAM_LIVE_KEY for a Live key. Every example reads it from there.
  • Never put it in code, a repository, a URL, a log, a browser page or a mobile app: anyone who can read the bundle can read the key.
  • If it may have been seen, revoke it and create another.

Then send your first order: Send your own API order.

Allowed IP addresses

A key can be limited to the addresses your servers call from. In your dashboard, open the key under Security, API access, and choose Change allowed IP addresses. Enter the public IP addresses your backend servers use to call the Nasfam Business API.

  • One per line, up to 20: an IPv4 address such as 203.0.113.10, an IPv6 address such as 2001:db8::10, or a CIDR range such as 203.0.113.0/24 or 2001:db8::/48.
  • Write a range from its first address, no wider than /8 for IPv4 or /16 for IPv6.
  • Use your servers' addresses. The address the dashboard shows as your browser's is where you are signed in from, not where your servers call from.
  • Where the key says Enforced, a request with it from any other address is refused with ip_not_allowed. Where it says Recorded, not enforced yet, the list is kept and requests from other addresses are still accepted.
  • If your servers' addresses change, through autoscaling, a dynamic cloud address or a new proxy, add the new ones before they start calling.

Rotate and revoke

Rotate a key to replace it: its successor keeps the same permissions and expiry, its secret is shown once, and the old key ends at once or after an overlap you choose, of at most 7 days. Revoke a key you no longer trust; it is never restored. A revoked key is refused from the next request on, with invalid_api_key; a request already accepted finishes. An expired key is refused with key_expired.

If a key may have leaked, revoke it first and investigate afterwards.

One key per environment

  • nbk_test_ keys work on the sandbox host only, and anyone with an account can create one.
  • nbk_live_ keys work on the Live host, https://api.nasfampay.com/v1, only, and exist only for a workspace activated for Live.

A key sent to the other host is refused with key_environment_mismatch, and a key without the right to an operation with insufficient_scope.