What Opey Can Do
Consents, entitlements and the accountable user: what Opey may do for you.
What Opey Can and Cannot Do on Your Behalf
Opey is an AI agent. When it calls the OBP API for you it does not use your login. Every action runs under a short-lived Consent that you approve in the chat, and that consent is built from the Entitlements and account Views you hold at that moment. This page explains the moving parts and what they mean in practice.
The Terms
| Term | Meaning |
|---|---|
| Entitlement | A Role granted to a User, optionally scoped to one bank: the pair (role_name, bank_id). System-wide roles have an empty bank_id. See your own on the Entitlements page. |
| View | Permission to see or act on a specific account: the triple (bank_id, account_id, view_id), e.g. owner or auditor. See Account Access. |
| My resources | Your own personal records that a consent may act on for you, for example your rows in a personal dynamic entity: the entry (bank_id, entity_name, actions) under my_resources. Owned rather than granted, so no role is involved and nothing can be "not held". Records Opey writes this way belong to you. |
| Consent | A signed grant (a JWT) that lets a Consumer act with a fixed list of entitlements, views and my resources for a limited time. Opey's consents last one hour. |
| Consent user | The identity OBP creates for each consent. Calls made with the consent JWT run as this user, which holds exactly the entitlements and views embedded in the JWT and nothing else. |
| Accountable user | The human who granted the consent: the owner of anything durable the call creates. Endpoints that have been made consent-aware attribute their side effects to this user rather than to the consent user; not every endpoint has been, see Three Identities, One Job Each and Attribution is not yet universal below. |
| Consent reference id | A stable identifier for a consent, recorded on every API call made with it. Filter your Activity Dashboard by it to see exactly what Opey did. |
How One Tool Call Gets Authorised
- Opey calls the API without credentials. The OBP MCP server replies
consent_required, naming the endpoint and the roles its resource doc requires. Nothing has reached OBP yet. - The chat shows a consent card. It lists the exact entitlement pairs the consent will carry, computed from your current entitlements, any account views you picked in the Working accounts picker, and, for actions on your own records, which of them Opey may read or write.
- You click Grant. The Portal re-reads your entitlements from OBP, picks the stored pair for each required role, reuses an existing unexpired consent if one already covers the request, and otherwise creates a new one. Your login token never leaves the Portal.
- Opey retries with the consent JWT. OBP runs the call as the consent user. Opey keeps the JWT for later calls that need the same roles, until it expires.
- You can watch it. The chip under the chat input shows the consent Opey is using now, with its reference id and the roles and views it carries.
What Opey Can Do
- Anything your entitlements allow at the moment you grant the consent, limited to the pairs that consent embeds. If you hold
CanCreateBank, Opey can create a bank. If you holdCanCreateAccountatbank-a, it can open accounts there and nowhere else. - Read or act on accounts you picked. View-scoped endpoints (balances, transactions, account details) work only for the
(bank, account, view)triples you selected in the Working accounts picker. No pick, no data. - Grant roles at a bank you administer. If you hold
CanCreateEntitlementAtOneBankat a bank, Opey can add roles to users at that bank under a consent carrying that pair. Creating a bank grants you this role there automatically. - Create things that belong to you, where the endpoint supports it. Roles Opey grants always go to humans, a bank Opey creates grants its admin role to you, and an account opened through the v7 endpoint is held by you. Every call is logged against your user and the consent's reference id.
- Work on your own records. Personal dynamic entity endpoints (the
/myroutes) need no role from you, but Opey reaches them only through a consent whosemy_resourcesnames the entity and whether it may read or write. What it writes there is yours, not the consent user's. - Reuse a consent. Repeat actions needing the same roles, views and my resources reuse the same consent for up to an hour, so you are not asked again and again.
What Opey Cannot Do
- Exceed your entitlements. OBP refuses to put a pair into a consent that you do not hold (
OBP-35013). If a required role is missing, the consent card tells you which role at which bank, and what to do next. - Use entitlements you gain later. A consent is a snapshot. Roles you receive after it was created, whether granted by an admin or as a side effect of an earlier Opey action, are invisible to it. Retry the action and grant a fresh consent; the chat shows a notice when this happens.
- Hold the system-wide granting role.
CanCreateEntitlementAtAnyBankis never allowed in a consent (OBP-35033), even if you hold it. Grant yourself the bank-scopedCanCreateEntitlementAtOneBankfirst, then Opey can grant roles at that bank. - Use virtual roles. Super admin powers are not stored entitlements, so they cannot be embedded in a consent. Opey acting for a super admin has only that admin's stored pairs.
- See your login. Opey never receives your session, OAuth token, or DirectLogin token, and it will never ask for one. If it appears to, deny the request.
- Hold roles itself. The consent user cannot be granted durable roles. A grant that names it is either redirected to you or rejected, so nothing accumulates on the agent identity. Other kinds of durable object can still end up attached to it, see above.
Three Identities, One Job Each
Every call Opey makes involves three identities, and the design is easiest to reason about when each is given exactly one job.
- The consent user is the actor. It authenticates the call, its embedded entitlements and views are what OBP checks, and it is what the API metrics record as
user_id. That is correct and deliberate: the log says truthfully that this agent identity made this call. - The consent reference id is the link. It is stamped on every metric row for the call, and it is how you get from the actor back to the human who granted the consent and to the exact scope they granted.
- The accountable user is the owner. Anything durable the call creates for a person, grants to a person, or links to a person records this id, never the consent user's.
The agent owns nothing durable. The only rows that belong to the consent user are the consent's own authorisation, its views and its copied entitlements, and they belong to it precisely so that they die with it. Everything else is the human's.
There is no single switch that makes this true, because OBP was written with one user id doing all three jobs. Every place that stores a user reference has to be visited once and told which job it is doing. That is a one-time sort rather than an ongoing judgement call, and it is what the section after next tracks.
An Old Pattern: Real and Effective Identity
This split is not new. Systems that take delegation seriously have carried two identities per request for decades. OBP is adopting the same model: the consent user is the effective identity, the accountable user is the real one, and the consent reference id is the audit link between them.
| System | Effective identity (permissions) | Real identity (ownership, audit) |
|---|---|---|
| Unix | euid after setuid, or the target user under sudo | ruid, and SUDO_USER in the log |
| PostgreSQL | current_user after SET ROLE | session_user |
| SQL Server | the principal named in EXECUTE AS | ORIGINAL_LOGIN() |
| OAuth token exchange (RFC 8693) | act, the acting party | sub, the party acted for |
| OBP under a consent | consent user: embedded entitlements and views, metrics user_id | accountable user: creator, holder, grant target; linked by consent_reference_id |
In each of these, permission checks use the effective identity and anything durable is recorded against the real one, and the storage layer applies that default so individual code paths do not have to remember it. That is the direction OBP is taking: the consent user keeps the isolation that makes authorisation watertight, and the persistence layer resolves the accountable user for everything it creates on a person's behalf. The alternatives, letting the agent act fully as the human or making the agent a durable principal of its own, are not open here: the first would bypass the consent's scope, and the second would leave objects owned by an identity that expires in an hour.
Attribution Is Not Yet Universal
Calls run as the consent user so that authorisation is watertight. The flip side is that any endpoint which stores "who did this" or "who owns this" has to choose the accountable human deliberately, and only some do today. What is guaranteed:
- Entitlement grants. A grant aimed at a consent user is redirected to the human who granted the consent, or rejected outright by the newer endpoints. The consent user can never accumulate roles.
- Bank creation. The automatic
CanCreateEntitlementAtOneBankgrant goes to you. - Account creation on v7. The holder defaults to you, and naming the consent user explicitly is rejected.
- Account applications on v3.1. The applicant is you, and the holder on approval is the applicant.
- Dynamic entity roles. The automatic grants on creating a dynamic entity go to you.
Anything else that records a user, such as older account-creation endpoints, customer links, auth contexts or the creator of a transaction request, may still name the consent user. Prefer the newest API version for actions that create durable objects, check the owner or holder in the response, and treat a consent user id where a human was expected as a bug to report.
Identity Under a Consent
Calling GET /users/current with a consent JWT returns the consent user, with the
accountable human under on_behalf_of. Anything that needs a human user id, such as
granting a role or naming an account holder, must use that nested id. Passing the consent user's id
is rejected with a clear error.
GET https://YOUR_OBP_HOST/obp/v7.0.0/users/current
Consent-JWT: <the consent JWT>
{
"user_id": "<consent user id>",
"entitlements": { "list": [ { "role_name": "CanCreateAccount", "bank_id": "bank-a" } ] },
"on_behalf_of": {
"user_id": "<your user id>",
...
}
}Worked Example: Create a Bank, Then an Account
- "Create a bank called
friday.bank." Opey needsCanCreateBank. You grant a consent carrying it. The bank is created and OBP grants youCanCreateEntitlementAtOneBankatfriday.bank. The chat shows a "you gained a new entitlement" notice. - "Now create an account there." Opey needs
CanCreateAccountatfriday.bank, which you do not hold. The consent card refuses and says you can grant it to yourself. - Opey offers to grant it. You approve a consent carrying
CanCreateEntitlementAtOneBankatfriday.bank. The role lands on you. - Opey retries the account creation. A fresh consent now carries
CanCreateAccountatfriday.bank, and the v7 endpoint creates the account with you as holder.
Two consents were minted for the escalation and one more for the account. Each is visible on My Consents and traceable on the Activity Dashboard by reference id.
Quick Reference
| You want Opey to… | You need | Possible? |
|---|---|---|
| List banks, read glossary or resource docs | Nothing. Public endpoints need no consent. | Yes |
| Create a bank | CanCreateBank | Yes |
| Open an account at a bank | CanCreateAccount at that bank | Yes. On the v7 endpoint you become the holder. |
| Read balances or transactions | A view on that account, picked in Working accounts | Yes, for picked accounts only |
| Grant a role to a user at one bank | CanCreateEntitlementAtOneBank at that bank | Yes |
| Grant a role at any bank | CanCreateEntitlementAtAnyBank | No. Never allowed in a consent. Grant yourself the one-bank role first. |
| Use a role you were given a minute ago | A fresh consent | Yes, after you retry and grant again |
| Act with your super admin powers | A stored entitlement for the role | No. Virtual roles cannot be embedded. |
Related
- Opey — what the assistant is and how to talk to it
- Consents — the consent model in full
- Account Access — how Views control data access
- Agents and MCP — connect your own agents the same way
- My Entitlements — see and grant your roles
- My Consents — the consents Opey has been given
- Consent endpoints in the API Explorer