Skip to main content
The Sumvin platform exposes two API surfaces with different authentication mechanisms.

​
Platform API — JWT Authentication

All Platform API requests require a valid JWT passed in a custom header. The API supports multiple authentication providers — your platform administrator configures which provider to use.

​
Making Authenticated Requests

Pass the JWT from your auth provider in the x-juno-jwt header: 
curl https://api.sumvin.com/v0/user/me \
  -H "x-juno-jwt: <your-jwt-token>"
If your Platform API credentials belong to more than one Sumvin organisation, scope the request to a specific org with the optional x-juno-orgid header: 
curl https://api.sumvin.com/v0/user/me \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>"
x-juno-orgid is optional. Include it when your Platform API credentials belong to more than one Sumvin organisation (multi-tenant auth), to scope the request to a specific org. Single-tenant integrations can omit it. The header value is the organisation’s external ID from the SIS Dashboard.
The Platform API uses x-juno-jwt, not the standard Authorization: Bearer header.

​
Supported Auth Providers

ProviderDescription
Dynamic LabsWeb3-native auth with wallet and email login
PrivyEmbedded wallets and email/SMS/social login, with MPC key management
SIWESign-In With Ethereum (EIP-4361) — direct wallet-based auth
Which providers are active is configured per environment in the SIS Dashboard. Your platform is configured with one or more providers — refer to your provider’s SDK documentation for how to obtain JWTs.

​
Token Requirements

The JWT must include these standard claims:
ClaimRequiredDescription
subYesUser’s unique identifier from the auth provider
expYesToken expiration time (Unix timestamp)
The API validates the token against the configured provider’s JWKS endpoint. Expired or tampered tokens are rejected.

​
User Identity

The API resolves user identity from the JWT — you never pass user_id in URLs or request bodies. Endpoints scoped to “the current user” derive identity from the token rather than a path parameter. For example: GET /v0/user/me — Fetch the current user. POST /v0/user/me/onboarding/submit — Submit onboarding for the current user. On first request, if no user exists for the JWT’s sub claim, you must create one: 
curl -X POST https://api.sumvin.com/v0/user/ \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "chain_id": 1329
  }'
Subsequent requests with the same JWT will resolve to this user.

​
SIS API — API Key Authentication

The Sumvin Identity Service (SIS) uses API key authentication via the Authorization: Bearer header. 
curl https://sis.sumvin.com/v0/users/sr:us:person:safe:0x... \
  -H "Authorization: Bearer <your-api-key>"
SIS API keys are issued during partner onboarding. Contact your account manager to obtain your API key.
API keys are scoped to your registered external party identity and determine which data fields you can access when looking up users by . For more on the SIS API and identity concepts, see Identity & PINTs.

​
Error Responses

Authentication failures return RFC 7807 Problem Details: 
{
  "type": "https://api.sumvin.com/errors/usr-401-001",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid authentication token",
  "error_code": "USR-401-001"
}
StatusMeaning
401 UnauthorizedMissing, expired, or invalid JWT / API key
403 ForbiddenToken is valid but the user lacks required permissions
404 Not FoundToken is valid but no user account exists (call POST /v0/user/ first)

​
Request Headers Summary

HeaderAPI SurfaceRequiredDescription
x-juno-jwtPlatform APIYesJWT from your configured auth provider
x-juno-orgidPlatform APIMulti-tenant onlyScopes the request to a specific org when the caller belongs to multiple orgs.
Authorization: BearerSIS APIYesAPI key issued during partner onboarding
Content-TypeBothFor POST/PUT/PATCHapplication/json
X-Timestamp-FormatPlatform APINoSet to iso8601 for ISO 8601 timestamps