Authentication
All API requests require a valid JWT passed in a custom header. The API supports multiple authentication providers — your platform administrator will configure 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>"
The API uses x-juno-jwt, not the standard Authorization: Bearer header.
Supported Auth Providers
| Provider | Description |
|---|
| Dynamic Labs | Web3-native auth with wallet and email login |
| Clerk | Traditional auth with email, phone, and social login |
Token Requirements
The JWT must include these standard claims:
| Claim | Required | Description |
|---|
sub | Yes | User’s unique identifier from the auth provider |
exp | Yes | Token expiration time (Unix timestamp) |
User Identity
The API resolves user identity from the JWT — you never pass user_id in URLs or request bodies. All endpoints scoped to “the current user” use GET /v0/user/me, POST /v0/user/me/onboarding/submit, etc.
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": 8453
}'
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"
}
| Status | Meaning |
|---|
| 401 Unauthorized | Missing, expired, or invalid JWT |
| 403 Forbidden | Token is valid but the user lacks required permissions |
| 404 Not Found | Token is valid but no user account exists (call POST /v0/user/ first) |
| Header | Required | Description |
|---|
x-juno-jwt | Yes | JWT from your configured auth provider |
Content-Type | For POST/PUT/PATCH | application/json |
X-Timestamp-Format | No | Set to iso8601 for ISO 8601 timestamps instead of epoch milliseconds |
