Authentication and Credentials
Select the credential and team-context contract for each surface
Keep credentials on a trusted backend. Never place a team API key, partner API key, or webhook secret in browser code.
Getting Credentials
Team API keys are created in the VRPlatform dashboard settings. Partner API keys are issued by VRPlatform during partner onboarding; contact VRPlatform to become a partner.
| Credential | Header | Use |
|---|---|---|
| Team API key | x-api-key: <team-api-key> | Direct backend calls for one or more teams |
| Partner API key | x-api-key: <partner-api-key> | Partner backend and managed-team calls |
| Embedded session | Authorization: Bearer <token> | Short-lived iframe product calls |
| Interactive session | Authorization: Bearer <token> | Signed-in or OAuth user calls |
API Keys
Use x-api-key on backend product API requests. A key that can access more
than one team must select the target with x-team-id. A single-team key can
omit the header when the route can resolve its only accessible team.
Partner-scoped collections such as GET /teams operate across managed teams
and need no managed-team selection. When the portfolio spans regions, use
x-data-region on supported collection reads to select one regional slice;
the partner API key remains the authorization context. Team-scoped routes (for
example GET /team, GET /transactions) require a selected team and ignore
x-data-region.
Partner keys are issued for one Worker audience and reviewed versioned capability bundles. A route must be explicitly available to partner credentials and the key must contain every required primitive scope. Write access does not imply delete, publish, pay, execute, import, or journal-posting access.
GET /me is a bearer-user bootstrap route for interactive and embedded
sessions. Partner API keys resolve their partner or managed-team context
through the partner and team endpoints; they cannot call /me.
Embedded Sessions
A partner backend sends its API key to
POST /partner/embed-sessions. It receives a 60-second, single-use portal URL,
not the bearer token. The iframe exchanges the fragment code directly and
keeps its 15-minute report-or-statement session in memory. The token is bound
to one user, team, audience, and read-only bundle set; a conflicting team
header or an unclassified route is rejected.
Failed Authentication
Branch on the HTTP status and the structured API error code (see the
Error contract). Do not parse the
human-readable message. When 401 or 403 responses repeat, send the user
back to credential, access-scope, and team-context checks; do not fall back to
another credential automatically.