Session and context

Many workflows need both an API key and an acting profile/team. Each route documents which context modes it accepts.

Session context#

When a route requires a session:

  1. Complete OTP verification to receive a session token.
  2. Send Authorization: Bearer <session> together with x-api-key.
  3. The API acts as the profile/team selected during verification.

Sending x-profile-id or x-team-id does not switch context on session-only routes.

curl -sS https://api-stg.vudy.app/v1/profile \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"
await fetch("https://api-stg.vudy.app/v1/profile", {
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
	},
});

Sessions expire. Call GET /v1/auth/refresh-session before the current session expires and replace the stored token when the response contains a new data.session.

Header context#

Routes that support header context can be called without a session when you supply:

  • x-api-key
  • x-profile-id
  • x-team-id
curl -sS https://api-stg.vudy.app/channels/quote \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{"capabilityId":"CAPABILITY_UUID","amount":100,"params":{}}'

Both headers are required together, and the profile must belong to the team. Do not send these headers as a substitute on a session-only route.

Conditional routes#

Depending on the endpoint, a conditional route can resolve context from:

  1. A valid session (Authorization: Bearer …)
  2. Explicit x-profile-id + x-team-id
  3. Profile/team context associated with a team-scoped API key

If a valid session is present, its context takes precedence. Without any usable context, the API commonly returns 401; a route can return 403 when context is required for the requested action. Inspect error.code rather than matching message text.

Switching profile or team#

To act as another profile in a session-authenticated flow:

  1. Call POST /v1/auth/send-otp for the same email
  2. Call POST /v1/auth/verify-otp with the desired profileId
  3. Use the new session for subsequent calls

Next steps#