Get Auth Roles
/v1/auth/rolesorg.permission.auth_role.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Gets available organization roles.
Role groups
A role group, called a permission set in the Kustomer app, is a named bundle of roles that decides what its members can see and do. Kustomer provides built-in role groups such as Administrator, and admins can create custom ones and assign them to users and teams.
Permissions in Kustomer are expressed as roles: dot-separated strings such as org.permission.customer.read or org.admin.klass.write (see how roles are named). Rather than giving each person a list of roles, admins group them into role groups and assign those. A user can have one role group assigned directly, in the user's roleGroups, and can get more through the teams they belong to. Changing a role group's roles changes what every member can do.
System and custom role groups
system: true |
system: false |
|
|---|---|---|
| Created by | Kustomer, in every org (for example Administrator and Manager) | Your admins |
| Can be changed | No. Updating or deleting one fails with 409. |
Yes |
Every role group has a name (up to 255 characters), an optional description (up to 1,024) and roles, a list of unique role strings. GET /v1/auth/roles lists the top-level roles available to your org. You can only put roles in a role group that you hold yourself; anything else fails with 400.
Outbound brand visibility
meta.outboundBrandVisibility limits which email From addresses members can see, based on the brands those addresses are mapped to. brandIds lists the visible brands, and includeUnassigned also shows addresses that aren't mapped to any brand. The filter applies only when a client requests GET /v1/outboundAccounts with applyOutboundBrandVisibility=true. A user in several role groups, directly or through teams, sees the union of their brands, and users who can edit role groups are never filtered. Send null to clear the setting. An empty allowlist (brandIds: [] with includeUnassigned: false) is different from no setting: it hides every address when the filter is applied.
Which endpoint to use
| To | Call |
|---|---|
| See the roles you can put in a role group | GET /v1/auth/roles |
| List system and custom role groups | GET /v1/role-groups |
| Read one role group and its roles | GET /v1/role-groups/{id} |
| Create, update or delete a custom role group | POST /v1/role-groups, PUT /v1/role-groups/{id} or DELETE /v1/role-groups/{id} |
Any signed-in user or API key can read role groups; creating, changing and deleting them needs a role group write role. A role group that is still assigned to a user or a team can't be deleted (409), so move those users and teams to another role group first. Role groups don't list their members: to give a person a role group, set roleGroups on the user.
Responses
OK