Authorization

The Sales Channel Services API uses role-based access control (RBAC) to assign and manage rights for users. If a request is made by a user who lacks the needed authorization, the request will instead return either an HTTP 403 Forbidden or HTTP 404 Not Found response. Not Found responses are reserved for cases where the application cannot determine whether the resource exists or whether the user is not able to interact with it.

Sales Channel Bindings

Before a user can get rights to act on a sales channel, it needs to be bound to the sales channel. This can be done using the following endpoints:

• POST /user-services/users/{userId}/saleschannel-binding/{salesChannelId}, to bind a user to a sales channel.
• DELETE /user-services/users/{userId}/saleschannel-binding/{salesChannelId}, to remove a user from a sales channel.

To check for the currently authenticated user to which sales channel you are bound to, make a request against GET /user-services/users/me/saleschannel-binding. In the response you will receive:

userId required	string The ID of the user which this role-binding is for.
salesChannelId required	string The ID of the sales channel which this role-binding is for.
roles required	Array of strings Items Enum: "TRADERONBOARDERPROPOSAL_VIEWER" "TRADERONBOARDERPROPOSAL_ACCEPTER" "TRADER_ADMINISTRATOR" "TRADER_VIEWER" "ROLE_ADMINISTRATOR" "ASSET_VIEWER" "ASSET_OFFRAMPER" "TRANSACTION_ADMINISTRATOR" "PRODUCTIONFACILITY_VIEWER" "SUPPLIER_VIEWER" "EVENT_VIEWER"

{

• "userId": "cl6aq4et20000mcxd38uh9w24",
• "salesChannelId": "cl6aq6sxp0004snxd516by16w",
• "roles": [

  • "TRADERONBOARDERPROPOSAL_VIEWER"

  ]

}

note

A user can be bound to at most one sales channel at a time.

Roles

When a user is bound to a sales channel, you can assign roles on that sales channel. Roles can be managed using:

• POST /user-services/users/{userId}/saleschannel-binding/{salesChannelId}/roles, to add a role to a user on the sales channel.
• DELETE /user-services/users/{userId}/saleschannel-binding/{salesChannelId}/roles, to remove a role from a user on the sales channel.

The following roles are available:

string

Enum: "TRADERONBOARDERPROPOSAL_VIEWER" "TRADERONBOARDERPROPOSAL_ACCEPTER" "TRADER_ADMINISTRATOR" "TRADER_VIEWER" "ROLE_ADMINISTRATOR" "ASSET_VIEWER" "ASSET_OFFRAMPER" "TRANSACTION_ADMINISTRATOR" "PRODUCTIONFACILITY_VIEWER" "SUPPLIER_VIEWER" "EVENT_VIEWER"

"TRADERONBOARDERPROPOSAL_VIEWER"

All roles follow the structure of {ENTITY}_{SCOPE}. Here, {ENTITY} is the name of the entity the user will get rights on, and {SCOPE} defines what kind of actions the user can do on that entity.

Some common scopes are:

• VIEWER which gives read-only rights.
• ADMINISTRATOR which gives full CRUD (create, read, update and delete) rights.

Exceptions

Certain roles do not fit into the default build-up of our roles. Often times this is because the scope of those roles are specific to some action on that entity. We will list those exceptions below and explain what they grant you rights to.

Role	Description
TRADERONBOARDERPROPOSAL_ACCEPTER	Allows accepting an existing trader onboarding proposal.

Examples

Below we will show some examples to illustrate how the roles work.

• The ROLE_ADMINISTRATOR role allows reading, creating and removing roles from the current user and other users. Yet, it does not allow creating or removing a user-sales channel binding. As such, the user to manage the roles on need to be already bound to the sales channel.
• The TRADERONBOARDERPROPOSAL_VIEWER role allows reading all trader onboarding proposals, but one cannot act on them.
• A TRADER_ADMINISTRATOR can read, update and create traders, but does not give rights to see or act on trader onboarding proposals.