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

TermMeaning
EntitlementA 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.
ViewPermission 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 resourcesYour 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.
ConsentA 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 userThe 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 userThe 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 idA 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 hold CanCreateAccount at bank-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 CanCreateEntitlementAtOneBank at 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 /my routes) need no role from you, but Opey reaches them only through a consent whose my_resources names 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. CanCreateEntitlementAtAnyBank is never allowed in a consent (OBP-35033), even if you hold it. Grant yourself the bank-scoped CanCreateEntitlementAtOneBank first, 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.

SystemEffective identity (permissions)Real identity (ownership, audit)
Unixeuid after setuid, or the target user under sudoruid, and SUDO_USER in the log
PostgreSQLcurrent_user after SET ROLEsession_user
SQL Serverthe principal named in EXECUTE ASORIGINAL_LOGIN()
OAuth token exchange (RFC 8693)act, the acting partysub, the party acted for
OBP under a consentconsent user: embedded entitlements and views, metrics user_idaccountable 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 CanCreateEntitlementAtOneBank grant 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

  1. "Create a bank called friday.bank." Opey needs CanCreateBank. You grant a consent carrying it. The bank is created and OBP grants you CanCreateEntitlementAtOneBank at friday.bank. The chat shows a "you gained a new entitlement" notice.
  2. "Now create an account there." Opey needs CanCreateAccount at friday.bank, which you do not hold. The consent card refuses and says you can grant it to yourself.
  3. Opey offers to grant it. You approve a consent carrying CanCreateEntitlementAtOneBank at friday.bank. The role lands on you.
  4. Opey retries the account creation. A fresh consent now carries CanCreateAccount at friday.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 needPossible?
List banks, read glossary or resource docsNothing. Public endpoints need no consent.Yes
Create a bankCanCreateBankYes
Open an account at a bankCanCreateAccount at that bankYes. On the v7 endpoint you become the holder.
Read balances or transactionsA view on that account, picked in Working accountsYes, for picked accounts only
Grant a role to a user at one bankCanCreateEntitlementAtOneBank at that bankYes
Grant a role at any bankCanCreateEntitlementAtAnyBankNo. Never allowed in a consent. Grant yourself the one-bank role first.
Use a role you were given a minute agoA fresh consentYes, after you retry and grant again
Act with your super admin powersA stored entitlement for the roleNo. Virtual roles cannot be embedded.

Related