API Keys

Niftipay uses API keys to authenticate server-to-server requests. You can create keys from the dashboard under Settings > API Keys. This page covers:

IP allowlisting (restrict which IPs can use your key)
Key rotation (swap keys with a zero-downtime grace period)

All endpoints below require authentication via x-api-key header or dashboard session.

IP Allowlisting

Restrict which server IPs are allowed to use your API key. When no IPs are configured, all IPs are allowed (opt-in model). Once you add at least one IP, only requests from allowlisted IPs will be accepted. Requests from other IPs will receive 403 Forbidden. Supported formats:

IPv4 — 203.0.113.50
IPv6 — 2001:db8::1
CIDR — 203.0.113.0/24

List allowed IPs

GET /api/user/api-keys/allowed-ips Returns your current IP allowlist. Example request

curl -X GET "https://www.niftipay.com/api/user/api-keys/allowed-ips" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response (no IPs configured)

{
  "allowedIps": [],
  "note": "No IP restrictions configured. All IPs can use your API key."
}

Response (IPs configured)

{
  "allowedIps": [
    {
      "id": "a1b2c3d4-...",
      "ip": "203.0.113.50",
      "label": "Production server",
      "createdAt": "2026-03-01T10:00:00.000Z"
    },
    {
      "id": "e5f6g7h8-...",
      "ip": "203.0.113.0/24",
      "label": "Office range",
      "createdAt": "2026-03-01T10:05:00.000Z"
    }
  ],
  "note": "2 IP(s) configured. Only these IPs can use your API key."
}

Add an IP to the allowlist

POST /api/user/api-keys/allowed-ips Body

{
  "ip": "203.0.113.50",
  "label": "Production server"
}

Field	Type	Required	Description
`ip`	string	Yes	IPv4, IPv6, or CIDR notation
`label`	string	No	Friendly label for your reference

Example request

curl -X POST "https://www.niftipay.com/api/user/api-keys/allowed-ips" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "ip": "203.0.113.50", "label": "Production server" }'

Response 201 Created

{
  "id": "a1b2c3d4-...",
  "ip": "203.0.113.50",
  "label": "Production server",
  "createdAt": "2026-03-01T10:00:00.000Z"
}

Error responses

400 — Invalid IP format
409 — IP already in allowlist

Remove an IP from the allowlist

DELETE /api/user/api-keys/allowed-ips Remove by id or by ip address (query parameter). Example request (by id)

curl -X DELETE "https://www.niftipay.com/api/user/api-keys/allowed-ips?id=a1b2c3d4-..." \
  -H "x-api-key: YOUR_API_KEY"

Example request (by ip)

curl -X DELETE "https://www.niftipay.com/api/user/api-keys/allowed-ips?ip=203.0.113.50" \
  -H "x-api-key: YOUR_API_KEY"

Response

{ "ok": true }

Error responses

400 — Missing id or ip query parameter
404 — IP not found in allowlist

IP allowlisting best practices

Always allowlist your production server IPs before going live
Use CIDR ranges if your servers share a subnet (e.g. 203.0.113.0/24)
Add before removing — when migrating servers, add the new IP first, verify it works, then remove the old one
If you lock yourself out (removed all valid IPs), you can manage allowlisted IPs from the dashboard session

API Key Rotation

Rotate your API key with zero downtime using a grace period. During the grace period, both the old and new keys are valid, giving you time to update your servers.

Rotate a key

POST /api/user/api-keys/rotate Body

{
  "oldKeyId": "old-key-id-here",
  "gracePeriodHours": 24,
  "name": "Production key v2"
}

Field	Type	Required	Description
`oldKeyId`	string	No	ID of the key to retire. If omitted, a new key is created without expiring the old one.
`gracePeriodHours`	number	No	Hours the old key stays valid (default: 24, max: 168 / 7 days)
`name`	string	No	Friendly name for the new key

Example request

curl -X POST "https://www.niftipay.com/api/user/api-keys/rotate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "oldKeyId": "abc123", "gracePeriodHours": 48, "name": "Production key v2" }'

Response

{
  "newKey": {
    "id": "def456",
    "key": "nftp_live_new_key_shown_once...",
    "name": "Production key v2",
    "createdAt": "2026-04-13T10:00:00.000Z"
  },
  "oldKey": {
    "id": "abc123",
    "expiresAt": "2026-04-15T10:00:00.000Z",
    "gracePeriodHours": 48
  },
  "message": "New key created. Old key expires at 2026-04-15T10:00:00.000Z (48h grace period)."
}

Response (without oldKeyId)

{
  "newKey": {
    "id": "def456",
    "key": "nftp_live_new_key_shown_once...",
    "name": "Production key v2",
    "createdAt": "2026-04-13T10:00:00.000Z"
  },
  "oldKey": null,
  "message": "New key created. Pass oldKeyId to set a grace period on the previous key."
}

The new key value is shown once. Store it securely immediately.

Rotation best practices

Recommended rotation steps

Create the new key with a grace period on the old key:

curl -X POST "https://www.niftipay.com/api/user/api-keys/rotate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "oldKeyId": "YOUR_OLD_KEY_ID", "gracePeriodHours": 48 }'

Store the new key in your environment variables / secret manager
Deploy your updated server(s) with the new key
Verify requests succeed with the new key
The old key expires automatically after the grace period — no manual cleanup needed

Tips

Use at least 24 hours of grace period to give yourself time to deploy across all environments
Rotate regularly (e.g. every 90 days) as a security best practice
If you need to revoke immediately (compromised key), set gracePeriodHours: 0 — the old key expires instantly
The new key has no expiration by default — it stays valid until you rotate again

Troubleshooting

Getting `403 Forbidden` after adding IPs

Verify your server’s outbound IP matches what you allowlisted (use curl ifconfig.me on your server)
If behind a load balancer or proxy, allowlist the external/NAT IP, not the internal one
CIDR notation must be valid (e.g. 203.0.113.0/24, not 203.0.113.0/33)

Locked out of the API

Log into the Niftipay dashboard (session auth bypasses IP allowlisting)
Remove or update the IP allowlist from Settings > API Keys

Old key stopped working before expected

Check the expiresAt value returned during rotation
Grace period is calculated from the moment of rotation, not from your last request

​API Keys

​IP Allowlisting

​List allowed IPs

​Add an IP to the allowlist

​Remove an IP from the allowlist

​IP allowlisting best practices

​API Key Rotation

​Rotate a key

​Rotation best practices

​Recommended rotation steps

​Tips

​Troubleshooting

​Getting 403 Forbidden after adding IPs

​Locked out of the API

​Old key stopped working before expected