Roles and permissions

A Sentisec workspace has exactly two roles: admin and member. The third state is holding no membership, which means no access to that workspace at all.

How the role is assigned

• Hosted. Your organisation membership decides it. The organisation admin role maps to Sentisec admin; every other role maps to member.
• Self-managed with your own OIDC provider. The role comes from the workspace claim your provider emits. A bare workspace id with no role means member — least privilege is always the default reading. See the self-managed OIDC guide for the claim shapes.
• Personal workspace. Someone with no organisation gets a personal workspace and is its sole admin, whatever any organisation role says.

Roles are resolved per workspace, per request, by the API — never cached in the browser. The interface predicts what you can do; the API is what enforces it.

What each role can do

The dividing line is workspace state. Changing how the workspace is configured, who belongs to it, and what it costs is admin work. Operating inside it — sending traffic, reading everything the workspace recorded, and stopping a session that is going wrong — is member work.

Approve a held call once

When a policy holds a tool call for review, for example under the approval policy for payments, outbound messages and contact changes, an admin can open it under Approvals and choose Approve once. The approval releases that one call, once, under the workspace's current policy, within the approval's lifetime: one hour by default and at most 24 hours. Approve once releases calls on the API endpoints: Messages, Chat Completions, Responses and Bedrock Converse.

Approve once needs the call's arguments. A workspace on metadata-only capture keeps none, so its held calls cannot be approved: nobody can approve a call they cannot see.

When the agent tries again

A held call never reaches your application. The approval takes effect when the agent makes the call again, from the same workspace key. Your application can read the decision from the held call's status before it re-sends; see calls waiting for approval.

• An exact retry is released. Same tool, same arguments, from any request.
• A retry of the same request that only rewords free text is released as approved. An AI agent writes its call afresh each time, so a reason or a message body rarely comes back word for word. When every other argument is unchanged, Sentisec sends your application the call the approver saw, word for word, under the retry's own call id. What the approver read is what runs, once. The agent's new wording is dropped, and the session records which arguments it had reworded. This applies to calls held for approval. When the review of a refused call offers Approve once, only an exact retry is released, and a reworded retry is refused again.
• Anything else is held again. A changed amount, recipient, account or id; an argument added or removed; a reworded retry from another request; a second retry after the approval was used; a changed policy or a revoked approval.

Free text is an argument whose value is a phrase or a sentence, such as a reason, a note or a message body: text with a space in it, on the approved call and on the retry. An id, an amount, an email address or an account number written without spaces is never free text. Only top-level arguments count; any change inside a nested object makes it another call. A tool call in the older Chat Completions function_call form, or a Responses tool item other than a function call, is released only by an exact retry.

When your application retries

Sentisec treats a retry as the same request when it comes from the same session, or from a run that opened with the same user message:

• send the same x-session-id on the retry as on the held call (see sessions), or
• run the request again from the same opening message.

A new job is a new request. Some applications open a new job, ticket event or conversation for every attempt, with new task text. That attempt is another request. There, only a word-for-word retry of the approved call is released. An agent rarely writes a reason or a message body the same way twice, so in practice the call is held again and a new review opens. To use the approval, re-send the original request rather than creating a new one: the same session id, or the same opening message.

Conversations that open with the same message share approvals. Two conversations whose first user message is exactly the same count as the same request, even with different session ids. If your application starts every conversation with one fixed message, an approval given in one conversation can release the same call, with reworded free text, in another conversation, once, while the approval lasts. What runs is still exactly the call the approver saw. To keep each approval with its own conversation, put what the conversation is about, such as the ticket or customer id, in its first message.

One review per request

Each request gets its own review. When the same call is held in two requests, for example two conversations that each ask for the same refund, each opens its own review under Approvals, linked to its own session. Open the one for the request that should go ahead: approving it releases that request's retry, reworded or exact. The other review is not approved with it and stays open. A word-for-word retry is the one exception, as above: any approval of that exact call can release it, once, from any request.

Calls are held only once the workspace blocks. On shadow and observe a call that would wait goes through, is recorded as "would ask", and opens no review, because there is nothing left to approve. What the review of a held call carries is in what the approver sees.

Who can approve:

• Hosted, organisation workspace: an admin of the organisation that owns the workspace.
• Self-managed with your own OIDC provider: a workspace admin, by the workspace claim your provider emits. This includes the first workspace of a self-managed install.
• Personal workspace: its owner.

A member who tries to approve gets 403 workspace_admin_required, and nothing is recorded. Nobody can approve their own request (403 self_approval_forbidden).

The approval is checked again when the agent retries. It is refused if the workspace was deleted or now belongs to another organisation. The role used is the one the approver held when they approved, so removing someone from your identity provider does not cancel an approval they already gave. Revoke it under Approvals, or let it expire.

Personal workspaces

A user without an organisation gets a personal workspace and is its only admin. The table above does not apply there — they hold every right in it.

Service accounts

There is no non-human account type. For CI and automation, mint a workspace API key under a person's identity and use that. The key carries the workspace's access, not the owner's role: it can send traffic and read, and it cannot change workspace configuration.

Rotate automation keys the same way you rotate any other credential — mint the replacement, deploy it, revoke the old one. Revocation takes effect on the next request.

Related

• Single Sign-On — wire your identity provider in
• Self-managed OIDC — how the workspace claim assigns roles
• SCIM — automated provisioning
• Audit and metrics — every role change is recorded