Roles and Groups

Access to the Documents Partner API is governed by a role. However, a role can only reach a user through a group — there is no other way in the STP Cloud.

This article explains both — and why this is actually good news for you.

The Three Roles

In user management, you'll see the display name; the technical name alongside it appears in configurations and when contacting support.

There are no additional roles for the Documents Partner API — and in particular, no partner-specific ones: the same three roles apply regardless of which partner product you're working with.

The partner product itself may come with its own roles. What an application like BEAMON AI distinguishes internally in terms of permissions is that product's own concern and has nothing to do with the roles described here. These three roles exclusively govern what is possible through the Documents Partner API in document management.

The role is only half the picture. It opens the interface. Which case files and documents a user can actually view and modify is still determined by the permission management in your local document management system for that specific user — see Licenses and Permissions.

Roles Are Always Assigned Through a Group

A role is assigned to a group, and users become members of that group. Anyone who isn't in a group that carries a role does not have that role.

User  →  Group  →  Role  →  Permissions

There is no way around the group. The STP Cloud does not support assigning roles directly to a user — user management simply doesn't offer that option. If you want to grant an account a permission, you add it to a group that carries the appropriate role. That's the only way.

Default Groups

To save you any setup work, we provide a ready-made group for each role. It is already present in every tenant:

Here's what they look like in user management under Groups — the Roles column shows which role each group carries:

In most cases, all you need to do is add the relevant user account to the appropriate group. There's nothing to create.

This is the recommended approach — it's the quickest, and it will remain correct if we add more roles in the future.

If a Default Group Is Missing

If a search doesn't turn up one of the three groups, it was either renamed, deleted, or the tenant was set up before the group existed. You can restore it with a single click:

Above the group list, you'll find the "Restore Missing Default Groups" button. It first shows you what will be created:

The list includes all missing default groups for the tenant, not just those for the Documents Partner API. In the screenshot, entries from other STP applications are blacked out; in your view, you'll see the groups for the applications your firm uses. Click Save to create them.

Two things to note:

• This action only creates — it doesn't change anything. Existing groups remain untouched, along with their members.
• Members are not restored. A restored group is empty; accounts must be added to it afterward.

Creating Custom Groups

The default groups are a convenience, not a requirement. As an administrator of your tenant, you can create your own groups and assign Documents Partner API roles to them — on their own or combined with roles from other STP applications.

This is particularly useful in two scenarios:

Keep in mind:

• A group can carry multiple roles, and a role can appear in multiple groups.
• A user can belong to multiple groups. Their permissions are the sum of the roles from all groups.
• Default groups remain in place even if you create your own. You can use them in parallel or leave them unused.

Combining DmsCloudApi.User and DmsCloudApi.User.Reader serves no purpose. DmsCloudApi.User already includes read access. If a user receives both roles through two different groups, they can write — the reader role doesn't change that. If an account should explicitly not be able to write, it must not be in any group that carries DmsCloudApi.User.

Which Role for Whom

Why the connector sign-in account only needs one role. DmsCloudApi.Connector authorizes exactly one thing: signing the connector in to the message broker. The connector never accesses the interface itself, so this role cannot read or write documents.

The actual work in document management happens under the account of the user whose request is being processed — not under the connector account. Assigning the other two roles to it would therefore serve no purpose — it would only expand that one account's permissions elsewhere.

If the same person also uses a partner application, they should of course also be added to the appropriate user group. But that reflects their role as a user, not their role as the connector.

When a Permission Isn't Working

The troubleshooting sequence that resolves most cases:

1. Is the account a member of a group that carries the role? Membership is the only way — without it, the account does not have the role.
2. Does the group actually carry the right role? For custom groups, it's worth checking the Roles column.
3. Does the group exist at all? If a default group is missing, it can be restored — see above.
4. Has a new token been obtained? Role changes only take effect with the next token — an existing token remains unchanged until it expires, typically after one hour.
5. Does the tenant have the appropriate license? Without it, no role will take effect — see Licenses and Permissions.

Further Reading

• Licenses and Permissions
• Getting Started