Skip to main content

API-key authentication and scope

Send your Nasam MM-API key in the key header on every resource request. Contact sales to obtain one.

GET /v1/brands HTTP/1.1
Host: backend.nasam.co
Accept: application/json
key: YOUR_API_KEY

Keep the key on your server or in a secret store. Do not put it in a URL, browser bundle, mobile application, or public log. Ask Nasam sales to rotate an exposed key. The getting started guide walks through the first scoped request.

Check access before an integration job​

  1. Make a small brand list request with the same key the job will use. Record the returned brand IDs.
  2. Read the operation's required grant in its reference page and choose only a brand inside the returned scope. A brand filter narrows the request; it is not proof of authority over that brand.
  3. For channel work, discover the brand's connected accounts and select the account ID the operation requires. A marketplace channel definition and a brand's connected account are different IDs.
  4. Treat a 401 as a key or authentication problem. For a 403, check the required grant and brand scope. For a 404, check the ID and scope without assuming the resource is globally absent.

Brand scope and permission are separate decisions​

The key's access determines which brands and operations it can use. A brandId in a path, query, or body selects a brand inside that access; it does not expand it. Omit a brandIds filter on reads that support it to use the caller's accessible set, or pass IDs to narrow that set. Start with GET /v1/brands to discover usable IDs.

An operation can also require a resource grant such as products.read, orders.write, or inventory.write. Where an operation requires a resource grant, its reference names it. For example, reading products and updating listings in bulk are separate capabilities. Account administrators can inspect the permission catalog and the user's grants. Access management explains changes to users, permissions, and brand assignments.

Marketplace authorization is a different workflow​

Connecting a marketplace account may require the merchant to authorize that marketplace. A channel connection can return an oauthUrl for that step. It authorizes Nasam to connect to the marketplace; it does not replace the MM-API key on your requests. Warehouse connections can have their own OAuth, certificate, or credential setup; see inventory and planning.

Use HTTPS. Send JSON request bodies as application/json; upload operations use the multipart fields shown in their operation pages. A failed authentication request returns an HTTP error using the standard error envelope.

If a scheduled job loses access after a change, stop writes, re-read the allowed brands and ask the account administrator to inspect grants and assignments. Do not broaden the job to an unfiltered brand request to work around a scoped failure.