Access and Permissions

Last Updated: 2026-09-03

Version: 1.1

VRPlatform uses the same primitive permission vocabulary for interactive users and API keys, but their bundles are separate grants.

Assigning a dashboard role never changes an API key. Granting an API-key bundle never changes a user membership.

Dashboard Roles

Dashboard roles are versioned ui:* bundles. The API expands the selected membership's bundles and returns the effective union as GET /me.membership.permissions.

Broad Team Access

Focused Team Access

Use this matrix for Operations and Read Only. View means read access. Other verbs name the additional actions granted in that area. A dash means the role does not grant that workflow.

Read Only includes team discovery so connection details and every listed settings view can resolve the selected team before loading its domain data.

GET /booking-channels supports both Integrations and Recurring Fees. It accepts either integrations:read or recurring-fees:read, so focused roles and API keys can resolve fee channel data without receiving integration access.

Transaction writes use one independent permission for each public type: transactions:expenses:write, transactions:deposits:write, transactions:transfers:write, and transactions:payouts:write. Operations receives only the expense permission. A type change requires both type permissions, and a mixed batch is rejected before any item is written when a required type permission is absent. Expense payment state still requires the separate payment permission supplied by ACH Payer.

Additive Privileges

These privileges are independent of team access. They add a sensitive or partner-specific capability and are not substitutes for a team-access role.

Partner Admin is available only to partner-team members. It covers partner members, managed teams, sessions, integrations, webhooks, audit, and API keys. ACH Payer is available on every team.

Global VRPlatform administrators cannot save owner or vendor bank details or execute, cancel, or recover ACH payments. Use a direct customer-team membership with Team Admin and ACH Payer when testing those workflows.

A managed team's deny policy can remove ACH execution from partner-derived access even when the partner member has ACH Payer. Direct memberships do not consume that policy.

Stable Bundle Names

For exact primitive permission strings, use GET /team/permission-bundles. Each catalog entry returns its complete permissions array. The tables above group those strings into UI workflows.

Every current dashboard bundle includes operations:read. There are no account-specific role assignments in V1.

Build a Role Picker

The API accepts multiple bundles and combines their permissions. The role picker should present exactly one team-access role: Team Admin, Standard Member, Operations, or Read Only. Do not expose the bundle array as an undifferentiated multi-select.

Then render the independent controls:

A partner-team member therefore receives Team access, Partner organization, Sensitive permissions, and Managed-team access sections. A non-partner member receives only Team access and Sensitive permissions.

Partner Admin is independent because it governs the parent partner organization; Team Admin governs the selected team's product and administrative access. ACH Payer remains independent because even Team Admin and Standard Member exclude money movement.

This hierarchy is product guidance. Until the API enforces it, clients must still handle existing members with any valid bundle array.

Gate navigation and actions using membership.permissions, never a primary role, bundle name, or legacy admin/user label. A member with no bundles can still load GET /me and GET /me/teams, but receives no product permissions.

Role Endpoints

Team Admins may replace their own assignment, including adding or removing ACH Payer. Removing their own Team Admin access is allowed only when another active direct access manager remains. The same final-manager rule applies to updates of other members.

Invitations and Compatibility Updates

New and legacy non-admin user memberships default to Standard Member. Existing team admins map to Team Admin, and existing partner-team admins also map to Partner Admin. Before permission mode is enabled for a user, authorization continues to follow the legacy role while the API keeps bundle data populated. An invitation delivery failure does not roll back a committed role change.

Partner-Member Team Reach

A partner member's permissions and team reach are independent. Configure the role picker and managed-team picker as separate controls.

Direct or owner membership on a child team remains available independently of partner assignments.

Before permission mode is enabled, users retain legacy broad partner reach. The stored all or assigned selection takes effect when permission mode is enabled, without a separate membership migration.

Resolve Access

A direct membership always wins over partner-derived access. Partner-derived access also applies the selected child team's partner deny policy.

Use GET /me/teams as the authoritative team-switcher source. Use GET /partner/members to render each partner member's roles, reach mode, and explicit assignments. Replace managed-team reach through PUT /partner/members/{userId}/memberships.

These changes never delete genuine direct or owner memberships.

Restrict Partner-Derived Access

A directly authorized Team Admin can manage the selected team's partner deny policy through GET and PUT /team/partner-permission-policy.

The policy stores primitive permission names. A denial wins over a granted bundle. Use it to withhold sensitive actions such as ACH execution, exports, or member-role management. The policy applies team-wide rather than to one bank account or one partner user.

New teams deny ach-payments:execute to partner-derived access by default, and the same denial is backfilled onto existing teams without replacing other denials. A directly authorized access manager must explicitly remove that denial before a partner can execute ACH for the client. Direct team membership never consumes the partner deny policy.

Partner API-Key Bundles

Partner keys may omit bundles for unrestricted partner access or declare up to the supported reviewed bundles. Restricted keys must have every primitive permission required by an operation.

Current early-access domain bundles include destructive operations supported by their domain. Credential management, self-service, internal, demo, and legacy routes remain unavailable to partner API keys.

Authentication expands stored bundle names using the current catalog, so a catalog update applies without replacing an existing key.

GET /api-tokens/permission-bundles returns the assignable API-token catalog. Each entry contains the stable name, display title, display description, and expanded permissions. Use this endpoint to render token bundle selectors instead of keeping a separate client-side list. It uses the same catalog shape as GET /team/permission-bundles for human roles.

Separate Recording From Money Movement

A restricted partner key must combine partner:payments:v1 and partner:ach-payments:v1 to move money. provider: "ramp" requires the applicable recording permission and ach-payments:execute before VRPlatform reads provider state or queues work.

Implementation Checklist

1. Load role and primitive-permission catalogs from the API.
2. Present one of Team Admin, Standard Member, Operations, or Read Only.
3. Keep partner administration, ACH, and managed-team reach independent.
4. Save complete replacement arrays, including intentional empty arrays.
5. Re-read GET /me after the selected user's own access changes.
6. Gate every action from effective primitive permissions.
7. Treat the final API response as authoritative under concurrent changes.

Related

• Authentication and Credentials
• Team Context
• Request Lifecycle
• Issue Embedded Sessions
• API Reference