Authentication
Most Vudy routes require an API key. Routes that act for a user or team may additionally require a session, explicit profile/team headers, or a team-scoped API key.
| Header | Purpose |
|---|
x-api-key | Dashboard-issued key (vudy_sandbox_… or vudy_production_…) |
Authorization | Bearer <session> returned by POST /v1/auth/verify-otp |
x-profile-id | Acting profile UUID on routes that support explicit header context |
x-team-id | Acting team UUID on routes that support explicit header context |
Patterns at a glance#
| Pattern | Required headers | Use |
|---|
| Public | none | GET /v1/maintenance |
| API key | x-api-key | Routes that do not need user/team context |
| API key + context headers | x-api-key, x-profile-id, x-team-id | Routes documented as supporting explicit header context |
| API key + session | x-api-key, Authorization: Bearer <session> | Session-authenticated user flows |
| Conditional | API key plus one supported context mode | Routes that explicitly accept session, headers, or key context |
Important rules#
- Always send the API key that belongs to the request host’s environment.
- Send
x-profile-id and x-team-id together. The profile must belong to the team. - If a valid session is present on a conditional route, its selected profile/team takes precedence over context headers.
- Session-only routes use the profile/team selected by OTP verification. To change that context, verify OTP again with the desired
profileId. - Route reference pages identify required API key permissions such as
WRITE or OTC_PROVIDER.
Auth failure statuses#
| Situation | Typical HTTP status |
|---|
| Missing/invalid API key, wrong environment, missing permissions | 403 |
| Missing/invalid required session | 401 |
| No usable context on a conditional route | 401 or route-level 403 |
| Rate or burst limit exceeded | 429 |
| Required OTP or KYC access gate closed | 503 |
Use the HTTP status and error.code together; do not branch on message text.
Next steps#