Authentication and API keys
Every request carries an API key as a Bearer token:
curl 'https://api.nasam.co/mm-api/v1/me' \
-H "Authorization: Bearer $NASAM_API_KEY"
{
"user": { "id": 412, "email": "ops@agency.example", "organizationId": 37 },
"apiKey": { "id": 7, "name": "ERP sync", "displayPrefix": "nsm_live_8fK2a1Q" }
}
GET /me tells you which key authenticated the request and which Nasam user it acts as. Call it once after you install a key.
Create a key
- Sign in to the Nasam app and open Settings → API keys at app.nasam.co/api-keys.
- Name the key after the system that will use it, for example
ERP sync, and create it. - Copy the token. It is shown once. Store it in your secret manager; Nasam keeps only a hash and cannot show it again.
Any Nasam user who belongs to an organization can create keys for themselves, except Nasam staff accounts. Production keys start with nsm_live_. Sandbox keys start with nsm_test_ and work only against the sandbox.
What a key can reach
A key acts as the user who created it. It has that user's brands and that user's permissions, read again on every request. If an administrator removes a brand from the user or takes away a permission in the app, the key loses it on its next request. If the user is deactivated, the key stops working.
So decide which user owns the integration's key. For an integration that should see every brand in an organization, create the key as a user with access to all of them. For one that should only read orders, create it as a user who holds only the order permissions it needs.
Each operation's reference page names the permission it requires, such as orders.read or inventory.write. A brandId or brandIds in a request selects brands inside the key's scope; it never widens it. On reads that accept brandIds, leaving it out means every brand in scope.
Keep keys on your server
Send keys only from server-side code. The API does not answer browser cross-origin requests, and a key in a browser bundle, mobile app, URL or log is readable by anyone who gets that file. Keys have a fixed nsm_live_ / nsm_test_ prefix and a checksum so secret scanners can find a leaked one.
Rotate a key with no downtime
A user can hold two active keys at once:
- Create a second key in the app.
- Deploy it to every system that uses the old key.
- Confirm the new key is in use: call GET
/mefrom each system, or check the old key's last-used time in the app. - Revoke the old key.
Revoke a key
Revoke a key in the app. It stops working on the next request. Revoke a key at once if it may have been exposed, then create a new one. Revoked keys stay listed in the app as a record of what existed.
401, 403 and 404
| Status | Meaning | What to do |
|---|---|---|
401 unauthorized | The key is missing, malformed, unknown or revoked, or its user cannot sign in. A sandbox key sent to production, or the reverse, is unknown there. | Check the header is Authorization: Bearer <key>, the host matches the key's prefix, and the key is active in the app. Retrying will not help. |
403 forbidden | The key is valid, but its user lacks the permission the operation requires, or the request names a brand outside the user's scope. | Compare the operation's required permission with the user's permissions, and the brand with GET /brands. Ask your Nasam administrator to change access if needed. |
404 not-found | The resource does not exist, or it belongs to a brand outside the key's scope. The API does not tell the two apart. | Check the ID and which brand it came from. Do not conclude the resource is absent for everyone. |
Errors use one format; see errors and limits. Repeated requests that fail authentication are throttled per IP address at 60 a minute.