Users, permissions, and assignments
User identity, permission grants, and brand assignments are related but distinct. A user's role and grants decide which operations are allowed. An assignment associates the user with a brand or a particular channel of that brand. Read both before changing access.
Decide what needs to change
| Need | Change | What it does not do |
|---|---|---|
| Invite someone or stop their sign-in | Users | Does not grant an operation or assign brand work |
Allow an operation such as products.read | Permissions | Does not create a brand or channel assignment |
| Give someone responsibility for a brand or channel | Assignments | Does not replace the permission grant required by the operation |
For a new collaborator, create the user, inspect the permission catalog and current grants, set the complete desired grant set, then create the assignment. Finally read both resources back. Use IDs from the API rather than matching display names.
Find and manage users
List users, read by ID, or look up an email. The user list accepts page, limit, role, organization, status, search, and other filters in its operation schema. Create, update, deactivate, and reactivate are separate actions. PATCH /v1/users/me is the current user's profile edit, limited to its contact fields. Password update has its own operation.
For creation, send email and role; emailTemplate defaults to NewUser if omitted. The role is one of OrgAdmin, OrgRegular, NasamAdmin, or NasamRegular where the caller is allowed to assign it. Use the returned user ID when assigning permissions or brands.
The list's status is derived from activity: Invited, Active, or Inactive. It differs from the isActive filter, which asks whether sign-in is enabled. A user can be invited and still have an active account. Creation sends an invitation email; record the returned ID instead of creating another user when the invitee has not signed in yet.
Grant permitted operations
GET /v1/permissions/catalog returns grantable resources, actions, and supported scopes. Build a permission picker from this catalog rather than a copied grant list. Read a user's grants before changing them.
PUT /v1/permissions/user/{userId} sends a permissions array. Each row has an action such as products.read, plus an optional organizationId or brandId where that grant supports the scope. This write replaces the user's entire grant set: include grants you intend to keep as well as additions. An organization administrator cannot assign a global grant or target another organization's user or brand. The response says the user must sign in again for changes to take effect; do not assume an existing session's grants change immediately.
For example, to grant product reads for brand 20, first include any grants already present in the GET response that you intend to preserve:
curl -X PUT 'https://backend.nasam.co/v1/permissions/user/42' \
-H 'key: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{"permissions":[{"action":"products.read","brandId":20}]}'
That example intentionally replaces all prior grants with one row. Do not send it to a user who must keep other access. A brand-scoped action must support brand scope in the catalog; an organization administrator can grant only within their organization. An empty array revokes the complete grant set. When access appears unchanged after a successful write, have the user sign in again, then re-read their grants before changing the payload.
Assign brand and channel work
Read your assignments or list assignments by brandId or userId. Create an assignment with userId and brandId; an optional saleChannelId narrows it to one channel, while omission assigns the whole brand. role is Owner by default or Collaborator. The same user cannot hold duplicate assignments for a brand/channel pair, and a new owner cannot displace an existing owner at that scope. Update can change channel or role; remove returns HTTP 204.
Before moving an assignment, list assignments for that brand and identify the current owner. The assignment id identifies the row to update or remove; saleChannelId identifies the channel scope. On PATCH, omitting saleChannelId moves the assignment to the whole brand, even if you intended only to change role. Send the existing saleChannelId when keeping a channel-specific assignment. If the target scope already has an owner, remove or reassign that owner first; a duplicate user/scope or second owner returns a conflict. Only administrators can write assignments, and the brand must be active and within the caller's scope.
After a change, re-read the user's grants and assignments. A brand ID passed to a resource operation still selects only within the caller's access. Authentication and scope explains that boundary.