Auth

These routes require a dashboard-issued API key in x-api-key. No route in this section requires an API-key permission flag.

Endpoints#

API-key validation failures return 403; rate-limit failures return 429. Session validation failures return 401. Error bodies use the standard success: false envelope and may originate in a called service; the route-owned errors below are the stable errors defined directly by each route.

POST /v1/auth/onboard#

Creates a user, initial profile, and either a new team or a profile in a pending invitation’s team.

Headers: x-api-key (required). The API key may be app-, team-, or profile-scoped.

Body

Response — 201

{
	"success": true,
	"data": {
		"team": { "id": "team-uuid" },
		"profile": {
			"id": "profile-uuid",
			"nickname": "johndoe",
			"suborgId": "opaque-organization-id"
		},
		"teamMember": {
			"profileId": "profile-uuid",
			"teamId": "team-uuid",
			"role": "admin"
		},
		"invitationAccepted": false,
		"walletCreated": true
	}
}

profile and teamMember are the objects returned by profile creation. Treat suborgId as opaque. walletCreated is false for country SV.

Route-owned errors

Malformed bodies return 400. Failures propagated from user, team, profile, wallet, or organization creation return 500 with that operation’s error code.

GET /v1/auth/referral/validate#

Checks whether a normalized referral code exists.

Headers: x-api-key (required).

Query

Response — 200

{
	"success": true,
	"data": { "exists": true }
}

Route-owned errors

Lookup failures return 500 with the propagated error.

GET /v1/auth/refresh-session#

Refreshes the current login session. Call it while the bearer session is valid.

Headers: x-api-key and Authorization: Bearer <session> (both required).

There are no path parameters, query parameters, or request body.

Response — 200

When a new session is minted:

{
	"success": true,
	"data": {
		"session": "new-session-token",
		"expirationTimestamp": 1760000000,
		"userType": "individual"
	}
}

When the presented token and stored session differ, the route synchronizes the stored session instead:

{
	"success": true,
	"data": {
		"message": "Session refreshed",
		"expirationTimestamp": 1760000000,
		"userType": "individual"
	}
}

expirationTimestamp can be omitted if the token cannot be decoded. userType is individual, business, or admin.

Route-owned errors

POST /v1/auth/send-otp#

Sends a login OTP and returns the identifier and matching profiles needed by verification.

Headers: x-api-key (required).

Body

Response — 201

{
	"success": true,
	"data": {
		"otpId": "otp-id",
		"identifier": "public-key-identifier",
		"profiles": [
			{
				"id": "profile-uuid",
				"nickname": "john_doe",
				"team": "John's Team",
				"userType": "individual"
			}
		]
	}
}

Route-owned errors

Malformed bodies return 400. Access-gate and OTP-provider failures use their propagated status/error.

POST /v1/auth/verify-otp#

Verifies a nine-character-or-longer OTP and creates a session for the selected profile.

Headers: x-api-key (required).

Body

Response — 200

{
	"success": true,
	"data": {
		"session": "session-token",
		"orgId": "opaque-organization-id",
		"country": "US",
		"userType": "individual",
		"teams": [
			{
				"teamId": "team-uuid",
				"teamName": "John's Team",
				"profileId": "profile-uuid",
				"profileNickname": "john_doe",
				"profileSuborgId": "opaque-organization-id",
				"profileRole": "admin",
				"userType": "individual",
				"teamDefaultReceiverWallet": "0x...",
				"teamProfileSuborgId": "opaque-organization-id"
			}
		]
	}
}

teamDefaultReceiverWallet may be null. Organization identifiers are opaque.

Route-owned errors

Malformed bodies return 400. User lookup and OTP/session-provider failures are propagated; the provider verification failure is currently returned as 500.