Authentication
Every call except the three token calls needs an access token in the x-access-token header. You get a token in two steps, then renew it before it expires.
| Item | Lifetime |
|---|---|
| One-time code | 10 minutes, and it works once |
| Access token | 24 hours |
| Refresh token | 30 days. Each refresh gives you a new one and cancels the old one. |
Step 1 — Get a one-time code
Send your client id. The call must come from an IP address registered for your client. In the sandbox the IP allow-list is optional.
curl "https://sandbox-api.nas.cards/open-api/v3/oauth/authorize?clientId=$CLIENT_ID"
{
"code": "000000",
"message": "success",
"data": {
"timestamp": 1758169263,
"code": "8655cf76c744615b57e631216ee006df"
}
}
Step 2 — Exchange the code for tokens
Send the client id and the code. The call must come from an IP address registered for your client.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/oauth/access-token" \
-H "Content-Type: application/json" \
-d '{"clientId": "<client-id>", "code": "<code-from-step-1>"}'
{
"code": "000000",
"message": "success",
"data": {
"accessToken": "6da5bf8a64b34ea30cfb75a6a5e8a9a28a59b8a3",
"refreshToken": "560d8accee67fb932688e568feca86c6b3866c4a858dce01b4cd66a73d7cc35a",
"expiresIn": 86400,
"timestamp": 1758169264
}
}
expiresIn is the access token lifetime in seconds. Store both tokens on your server only.
Step 3 — Call the API
Send the access token in the x-access-token header.
curl "https://sandbox-api.nas.cards/open-api/v3/accounts?accountId=<account-id>" \
-H "x-access-token: $ACCESS_TOKEN"
Step 4 — Renew the token
Renew with the refresh token before the access token expires. You can also renew after it has expired, until the refresh token itself expires.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/oauth/refresh-token" \
-H "Content-Type: application/json" \
-d '{"clientId": "<client-id>", "refreshToken": "<refresh-token>"}'
{
"code": "000000",
"message": "success",
"data": {
"accessToken": "200e66fc7e1f203f77a1bababee661cbc2f48095",
"refreshToken": "9b1f0c6d2a7e4f3c8d5a1b0e6f7c2d3a4b5c6d7e8f90a1b2c3d4e5f60718293a",
"expiresIn": 86400,
"expiresAt": 1758352187000,
"timestamp": 1758265787
}
}
A refresh token can be used once. The call spends the one you sent and returns a new one, so store the new refreshToken in its place. expiresAt is when the new access token expires, in milliseconds since the epoch. If you lose the refresh token, start again at Step 1.
Fetch a token at start-up and keep it in memory. When any call answers with code NB40102 (invalid access token), refresh once and retry that call once. If it fails again, start again at Step 1.
IP pinning
In production, NAS registers the IP addresses your calls come from. A call from any other address is refused with NB40305, including the token calls. Give NAS a fixed outbound address, or a short list, before you go live. To change the list, ask NAS.
In the sandbox, pinning is optional. If your sandbox client has pinned addresses, the same rule applies to it.
Keep your credentials safe
- Keep the client id and tokens on your server. Never ship them in a browser or a mobile app.
- Do not log tokens or the
x-access-tokenheader. - Ask NAS to rotate the client id if you suspect it has been exposed. Rotation cancels the old one.
Errors on the token calls
| Code | HTTP status | Meaning |
|---|---|---|
NB40101 | 401 | The client id, code or refresh token is not valid. A code works once and for 10 minutes. |
NB40002 | 400 | A required field is missing. |
NB40305 | 403 | The call came from an address that is not registered for your client. |
NB40304 | 403 | Your client is suspended. Contact NAS. |
See Errors for the full list.