Authenticate user and issue tokens

1 min

POST

https://api.upstartcommerce.com/api/v1/auth/login

Validates user credentials and issues JWT access and refresh tokens.

Tenant context is resolved in priority order:

Authorization: Bearer <guest-token> — tenant extracted from the guest token's tenant claim (preferred)
x-upstart-tenant header — explicit tenant selection (fallback, deprecated)

The guest token is issued by the /api/v1/auth/guest endpoint and carries the tenant (and site) context for the current browsing session. Clients should always present the guest token; the x-upstart-tenant header is retained for backwards compatibility only.

The token includes siteRoles containing all sites the user can access. Site context is determined at runtime via the x-upstart-site header on subsequent API calls, not at login time.

The response includes both an access token (short-lived, for API calls) and a refresh token (long-lived, for obtaining new access tokens).

acceptstringGenerated from available response content types

AuthorizationstringGuest token issued by <code>/api/v1/auth/guest</code>, carrying tenant (and site) context for the session. The <code>tenant</code> claim is extracted and used as the active tenant for this login. Falls back to <code>x-upstart-tenant</code> if absent or if the token cannot be parsed.

x-upstart-tenantstringTenant identifier for multi-tenant authentication. Required when user is authorized for multiple tenants. Optional when user has exactly one authorized tenant (auto-selected).

bodyobjectUser credentials for authentication

200Authentication result. Either: <ul> <li>Successful authentication with tokens (mfaRequired=false or absent)</li> <li>MFA challenge required (mfaRequired=true)</li> </ul>

400Bad request - invalid JSON, missing fields, or tenant selection required

401Invalid credentials

403Forbidden - unauthorized tenant or no authorized tenants

500Internal server error

curl --request POST \
     --url https://api.upstartcommerce.com/api/v1/auth/login \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data-raw '{
     "username": "[email protected]",
     "password": "securePassword123",
     "tokenType": "consumer"
     }'