Access approvals — AI Portal Docs

Some actions reach another person’s data or money, so they wait for a second person. The requester names what they need and why; somebody else approves or denies it. An approved request to reach data becomes a grant, checked every time the data is served. An approved budget request is written onto the person it names.

Key rules

Two people, always. Nobody decides their own request, or one about themselves.
The approver takes the request as written — no narrowing, no shortening.
Grants are checked on every read, so revoking takes effect immediately.
Every request expires. Undecided after seven days, or past its duration.
Everything is audited, including each read made under a grant.

Requests and grants

An access request names a kind, a scope, a reason, an optional reference such as a ticket number, and a duration. From the scope, the portal works out whose data it reaches; those people are its subjects.

	Reading conversations	Raising a budget
Needed to ask	`transcript.read`	nothing
Needed to approve	`transcript.approve`	`policy.manage`
Scope	chosen conversations, or one person’s conversations created between two dates	one amount in USD a month
Default duration	24 hours	1 hour
Longest duration	72 hours	1 hour
Use	any number of reads until it expires	one, spent by the approval itself

A grant over a date range covers the conversations that person created inside it. A conversation started before the range and continued inside it is outside the grant.
Approving a budget request writes the budget and spends the grant in the same decision, so it reaches Used within the second it was approved.
Older “sign in as a user” requests (scope: one person; default 1 hour, longest 24 hours) can still exist and be decided, but they are no longer consulted — see Impersonation.

Lifecycle

A request is Pending until somebody decides it, and expires after seven days if nobody does. Approving starts the grant’s clock, so a request approved two days late still lasts its full duration.

Status	Meaning
Pending	Waiting for a decision
Active	Approved and inside its duration
Denied	Refused, with a note saying why
Withdrawn	Cancelled by the requester before anybody decided
Revoked	Ended early by the requester or by an approver
Used	A single-use grant that has been spent
Expired	Undecided for seven days, or past its duration

Pending leads to Active, Denied, Withdrawn or Expired; Active leads to Revoked, Used or Expired.

The approver cannot narrow the scope or shorten the duration. A request that asks for too much is denied with a note, and the requester asks again.

Budget requests

Anybody may Ask for a higher budget for themselves — from Usage and budget. No capability raises a budget without approval, so none is needed to ask.

Ask

The request carries one figure: the USD a month you want to be held to. Beside it the portal records what you may spend today — your share of your department’s budget, or your own figure if you already have one.
Checks on send

A figure at or below your current one is refused. One request waits at a time; a second is refused until the first is decided or withdrawn.
Approve

An approver with policy.manage decides it in Access requests. The new budget reaches the model gateway first; if the gateway refuses the figure, the request keeps waiting and nothing is written.
Your own budget

Approval writes a personal budget carrying the asked figure and the five other limits you were already held to. It replaces your share of the department budget: you spend on a gateway record of your own, and your department’s pool loses nothing to you. It stays until an administrator changes or clears it on the Users screen.

How personal budgets fit with department budgets: Budgets and policy.

Who may decide

Somebody holding the kind’s approving capability decides, with two exceptions that apply to everyone:

Nobody decides their own request.
Nobody decides a request whose subjects include them.

Also:

Org Owner and Org Admin hold the approval capabilities.
transcript.approve may also go on a custom role, so a legal or data-protection team that does not otherwise administer the portal can approve.
impersonation.approve stays built-in and decides only older “sign in as a user” requests.
policy.manage decides budget requests — the same capability that writes a budget by hand. The seeded Department Lead role holds neither it nor department.manage, because both take the department from the request rather than from the caller.
The seeded Compliance Reviewer role asks and does not approve.
The requester may withdraw a pending request or hand back an active grant. Anybody who could have approved a grant may revoke it while it is active; it takes effect on the next read.

Impersonation

Impersonation — View as in the product — lets an administrator holding user.impersonate act as a named person in the organisation for 30 minutes, to reproduce a screen that visibility rules, department policy and effective capabilities all shape.

How it works:

The browser session keeps the administrator’s identity on a record of its own and carries the named person’s. Every check, rule and budget that runs afterwards is theirs — the seat re-read on each request, the effective capabilities, and the department a model call is billed to (it reaches the gateway on that person’s department key).
Nothing is issued at the identity provider. A token refresh during the window keeps the borrowed identity.
Leaving is a restore, not a second sign-in, and needs no capability — by then you are the other person, who may hold none.

Refused when:

The person holds a capability you lack. Org Admin lacks billing.manage, and borrowing the owner’s seat would reach it. Effective sets are compared, not tiers, so a member whose group grants a custom role you lack is refused too.
The seat is suspended. A session resolved as one is rejected on its next request.
It is yourself, or you are already viewing as someone.

How the window ends:

You press the button to leave.
The first request past the 30 minutes restores you automatically.
Signing out is not offered while it is open, because that ends your whole session; reaching sign-out anyway closes the window first. A session nobody touches again simply ends when the session does.

While viewing as someone, you can neither create, decide nor revoke an access request, and conversation grants are not honoured — a read that needs one is refused.

Audited: entering and leaving each write an admin event naming the administrator as actor and the person as target. The start records when the window closes; the end records when it opened, and is written on every way out — the button, the half hour running out, and signing out. Rows written in between (a chat turn, an uploaded file, an artifact) carry the person’s id, as if they had written them; the window the pair describes is what an auditor reads.

The organisation’s switch

Reading conversations has an approval switch under Admin console › Organisation. Raising a budget has none: there is no path that writes one person’s budget without a second administrator, so there is nothing to switch off.

What is audited

Creating, approving, denying, withdrawing and revoking a request each write an admin event naming the request.
Changing the switch writes an admin event.
Every read of a conversation, its files or a turn’s steps under a grant writes the usual content-access row, carrying the id of the grant it used.

See Audit and cost tracking.

Why it works this way

Why can't the approver trim a request?

The approver decides what was actually asked and justified. Editing it would approve something nobody requested; a denial with a note keeps the record honest.

Why is a grant checked on every read?

Because the check runs each time data is served, revoking or expiry takes effect on the very next read — there is no cached permission to wait out.

Under the hood

Adding a kind

A kind is declared in the approvals module with: the capability needed to approve it; the capability needed to ask (or none); default and longest duration; whether one use spends it; and its scope shape.

A kind that reaches someone’s data names a match function deciding whether a grant covers one access, given what the feature already knows about the target. The feature calls the shared grant check where it already checks its capability, and passes the returned grant id into whatever it records. A kind that changes a setting does its write when the decision is approved, before the decision is stored. Tables, the requests page, approval rules and audit events need no change.

Impersonation events

Admin events user.impersonate.start (carries the close time) and user.impersonate.stop (carries the open time). The session stores an impersonation record beside the identity it acts as; no scheduled job reads these records.