Profiles and teams

After authentication, most product actions run in the context of a profile belonging to a team.

Prerequisites#

  • Valid session from OTP onboarding
  • For team routes that allow server-to-server context: x-profile-id + x-team-id may be used instead of a session
  • Admin role for invitation and member-management mutations

Profiles#

List profiles#

curl -sS https://api-stg.vudy.app/v1/user/profiles \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"
const { data } = await fetch("https://api-stg.vudy.app/v1/user/profiles", {
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
	},
}).then((r) => r.json());
// data.profiles: [{ id, teamId, teamName, nickname, isDefault, ... }]

Set default profile#

curl -sS -X PUT https://api-stg.vudy.app/v1/user/default-profile \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"profileId":"PROFILE_UUID"}'

Setting the default does not change the active session context. Re-verify OTP with that profileId to act as it.

Read the active profile#

Session required. Context comes from the login session.

curl -sS https://api-stg.vudy.app/v1/profile \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"

Response includes profile, banks, user fields, user KYC badge, wallets, and optional imageUrl. For business-admin KYB status, use KYC status instead of relying on the profile KYC badge alone.

Update username, metadata, image, banks#

These profile mutations require API key + session:

ActionMethod / path
UsernamePATCH /v1/profile/username body { "nickname": "new-name" }
MetadataPATCH /v1/profile/metadata
Image upload URLPOST /v1/profile/image/upload-url
Confirm imagePOST /v1/profile/image
Banks CRUDPOST/GET/PATCH/DELETE /v1/profile/banks…
await fetch("https://api-stg.vudy.app/v1/profile/username", {
	method: "PATCH",
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({ nickname: "alex-r" }),
});

Teams#

Teams are created during onboarding as personal or business teams.

Invite a member (admin)#

curl -sS https://api-stg.vudy.app/v1/teams/invitations \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{"email":"teammate@example.com","role":"member"}'

The invitation remains pending until it is accepted during the invitee’s onboarding, cancelled, or expires.

List members and change roles#

curl -sS https://api-stg.vudy.app/v1/teams/members \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID"
curl -sS -X PATCH \
  "https://api-stg.vudy.app/v1/teams/members/PROFILE_UUID/role" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "x-profile-id: ADMIN_PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{"role":"developer"}'

Roles used in invitation and role-change examples include admin, member, developer, viewer, and analyst.

Other team settings#

Depending on role, teams expose metadata, tax info, countries, banks, notification email, default receiver wallet, images, and activity. See the Teams reference for endpoint contracts.

Manage integration API keys and webhook settings in the Vudy dashboard.

Next steps#