Authentication and Credentials

Last Updated: 2026-09-03

Version: 1.1

Keep credentials on a trusted backend. Never place a team API key, partner API key, or webhook secret in browser code.

Choose a Credential

Team and partner API keys use the same token-management endpoints. The team that owns the key determines whether it is a team or partner credential. Contact VRPlatform to register a team as a partner.

Create and Manage API Keys

A signed-in user with api-tokens:manage can list, create, reveal, and revoke keys for the selected team. A global VRPlatform administrator can do the same without joining that team. An API key cannot create or manage other keys.

VRPlatform generates the secret and returns it when the key is created. The token list shows metadata and a four-character hint; revealing a key returns its full value. Store the value in a secrets manager. Revocation applies to the next authenticated request.

POST /api-tokens
Authorization: Bearer <interactive-session>
x-team-id: <team-id>
Content-Type: application/json

Partner keys may omit bundles for unrestricted partner access or declare reviewed capability bundles. See Access and Permissions for the bundle catalog and payment boundaries.

Restrict Source IPs

API keys may contain up to 32 allowedIpCidrs entries. Individual IPv4 and IPv6 addresses are normalized to /32 and /128; networks are normalized to their CIDR boundary.

VRPlatform evaluates Cloudflare CF-Connecting-IP. It never trusts X-Forwarded-For for this restriction.

Select a Team

A key that can access multiple teams must send x-team-id on team-scoped routes. A single-team key may omit it when the route can resolve its only team.

Partner collections such as GET /teams use the partner itself as the authorization context and do not select a managed team. For portfolios across regions, supported collection routes use x-data-region to select one regional slice. Read Team Context before building team switching or regional portfolio requests.

Use Bearer Sessions

Interactive sessions call GET /me to load the selected membership, effective permissions, features, and team context. Product interfaces must gate actions using the returned effective permissions, not role labels.

Embedded sessions are issued by a partner backend and exchanged inside the iframe. Follow Issue Sessions for issuance, origin binding, renewal, and revocation.

Embedded bundles stay narrow. embed:banking:v1 grants the Plaid connect, complete, and configure sequence only; it does not grant general banking data or team administration. Audit events keep the end user as actor, identify the embedding partner as the represented organization, and use an embedded source.

When you send x-request-id, VRPlatform echoes it and stores it as the action's request identifier. If you omit it, VRPlatform generates a UUID for that HTTP request. Session, correlation, provider, trace, and Cloudflare Ray IDs are not used as request IDs.

Failed Authentication

Use the HTTP status and structured API error code; do not parse the message.

Do not retry with a different credential automatically. See the Error Contract for the shared response shape.

Next Steps

• Access and Permissions
• Team Context
• Issue Embedded Sessions
• API Reference