Skip to main content

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.

ItemLifetime
One-time code10 minutes, and it works once
Access token24 hours
Refresh token30 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"
Response GET /open-api/v3/oauth/authorize
{
"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>"}'
Response POST /open-api/v3/oauth/access-token
{
"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>"}'
Response POST /open-api/v3/oauth/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.

tip

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-token header.
  • Ask NAS to rotate the client id if you suspect it has been exposed. Rotation cancels the old one.

Errors on the token calls​

CodeHTTP statusMeaning
NB40101401The client id, code or refresh token is not valid. A code works once and for 10 minutes.
NB40002400A required field is missing.
NB40305403The call came from an address that is not registered for your client.
NB40304403Your client is suspended. Contact NAS.

See Errors for the full list.