Guides
End users
Only needed when an agent acts for one specific person (a patient, an account holder, a student, a policyholder), not just for your organization. That person agrees to the agent, can approve single actions, and can pause or turn it off at any time.
Requests without an endUserId are checked against the agent's scope, your rules and your approvers, exactly as before.
The four screens
Each is a hosted page (nothing to build) or a React component from @authentify2026/consent-widget you embed in your own app.
| Screen | What the person does | Hosted | Component |
|---|---|---|---|
| Consent | Allows or doesn’t allow one agent, seeing each action in plain words and what it won’t be able to do. | widget_url | AuthentifyConsentWidget |
| Single-action approval | Approves, denies, or denies and pauses the agent for one escalated action. | /approve | ActionApproval |
| Connected agents | Pauses, resumes or turns off each agent. | /my-agents | ConsentManager |
| Activity | Sees everything their agents did or tried for them, and downloads it. | /my-agents | ActivityFeed |
1. Ask for consent
Your server starts a consent session with your account key:
/api/v1/consent-sessionsaccount key, as Bearercurl -X POST https://www.authentify.bz/api/v1/consent-sessions \
-H "Authorization: Bearer $AUTHENTIFY_ACCOUNT_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "YOUR_AGENT_ID",
"customer_id": "YOUR_CUSTOMER_ID",
"end_user_id": "customer-42",
"scope": ["READ_RECORDS", "SCHEDULE_APPOINTMENT"],
"excluded_scope": ["SHARE_RECORDS"]
}'
# -> { "session_id": "sess_...", "expires_at": "...", "widget_url": "https://widget.authentify.bz?session=sess_..." }Send the person widget_url, or embed the widget:
import { AuthentifyConsentWidget } from '@authentify2026/consent-widget';
<AuthentifyConsentWidget sessionId={sessionId} onApprove={onGranted} onDecline={onDeclined} />You learn the answer from onApprove / onDecline or the consent_granted / consent_declined webhooks. A grant covers one agent and one person and lasts 30 days. scope must be within the agent's allowed actions.
Step-up verification (optional)
To have the person sign in to your app before the grant is issued, pass require_auth: true and set authRedirectUrl (or onAuthRedirect) on the widget. Your backend confirms with POST /api/v1/consent-sessions/:sessionId/confirm-auth; no consent is granted until it does. If your users sign in with Entra ID, you can instead pass the user's token as subject_token (see token exchange).
2. Name the person on each request
Send endUserId on that person's /api/v2/authorize calls. Without a live consent the request is denied with consent_required; paused gives consent_paused; an action they didn't agree to gives outside_consent_scope. Setting requires_end_user on the agent denies any request that leaves endUserId out (end_user_required).
3. Let the person approve single actions
Turn on end_user_approval for the agent (POST /api/v1/agents/:agentId/update). When a request that named endUserId escalates, the response says endUserCanDecide: true. Your backend asks for a link and sends it to the person (in-app, push, email or SMS):
/api/v2/approval-requests/:id/end-user-linkaccount keycurl -X POST https://www.authentify.bz/api/v2/approval-requests/$APPROVAL_REQUEST_ID/end-user-link \
-H "x-api-key: $AUTHENTIFY_ACCOUNT_KEY"
# -> { "url": "https://www.authentify.bz/approve?approval=euap_...", "expires_at": "...", "end_user_id": "customer-42" }The page shows the amount, the agent's stated reason and why they're being asked. Their answer resolves the request like an approver's vote and is sealed. The link works once and lasts 30 minutes.
Whoever holds it can decide the request. That's why /v2/authorize never returns it and agent keys can't request it.
4. Give the person their "my agents" page
From your app's account or settings screen, ask for a link and send the person to it:
/api/v2/end-users/:endUserId/portal-linkaccount keycurl -X POST https://www.authentify.bz/api/v2/end-users/customer-42/portal-link \
-H "x-api-key: $AUTHENTIFY_ACCOUNT_KEY"
# -> { "url": "https://www.authentify.bz/my-agents?portal=...", "expires_at": "...", "end_user_id": "customer-42" }The link works for 1 hour; ask for a new one each time. If the person's consents are tied to an identity provider, pass { "identity_provider_id": "..." }. To build these screens into your own app instead, embed ConsentManager and ActivityFeed.
Turning an agent back on
People can pause and resume, and they can turn an agent off. They can't turn it back on: only you can, by starting a new consent session that they approve. An agent can never quietly regain access. The same applies when the 30 days run out.
Events
consent_granted, consent_declined, consent_paused, consent_resumed and consent_revoked reach your webhooks. data.detail names the person (end_user_id), the consent_id, the scope and where it happened (source: consent_widget, consent_manager or action_approval).