Skip to main content
POST
/
api
/
sys
/
users
/
exchange
Exchange JWT
curl --request POST \
  --url https://spaces.nexudus.com/api/sys/users/exchange \
  --header 'Authorization: Basic <encoded-value>'
{
  "token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>",
  "400 Bad Request": {},
  "401 Unauthorized": {}
}

​
Exchange JWT

Converts a one-time JWT — issued during sign-up, email verification, password reset, or magic-link flows — into a standard bearer token and refresh token pair. The portal calls this immediately after any server-side operation that returns a raw JWT, so the customer is signed in without ever entering their password.
This endpoint is intended for server-issued JWTs passed back to the client (e.g. as part of a sign-up response). It is not for exchanging a customer’s email and password — use POST /api/token for credential-based sign-in.

​
Authentication

No authentication required. The JWT in the token parameter acts as the credential.

​
Query Parameters

​
token
string
required
The short-lived JWT to exchange. URL-encode this value. Obtained from server-side flows such as the sign-up response (Token field) or a magic-link email.
​
validForInMinutes
number
required
Lifetime of the issued bearer token in minutes. The portal passes 1440 (24 hours) for standard sign-in sessions.

​
Response

​
token
string
Bearer token to include in the Authorization header of all subsequent authenticated requests.
​
token_type
string
Token scheme. Always bearer.
​
expires_in
number
Lifetime of the bearer token in seconds.
​
refresh_token
string
Token used to obtain a new bearer token after it expires without requiring the customer to re-authenticate.

​
Examples

​
Exchange a JWT after sign-up

POST /api/sys/users/exchange?token=eyJhbGciOiJSUzI1NiJ9...&validForInMinutes=1440

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "7kMpQxRtZn2"
}

​
TypeScript Integration

import endpoints from '@/api/endpoints'
import { ExchangedToken } from '@/states/useAuthContext'

// `rawJwt` is the `Token` field returned by e.g. the sign-up endpoint
const response = await httpClient.post<ExchangedToken>(endpoints.system.auth.login(rawJwt))

if (response.data.token) {
  await saveSession({
    tokenResponse: {
      access_token: response.data.token,
      token_type: response.data.token_type,
      expires_in: response.data.expires_in,
      refresh_token: response.data.refresh_token,
    },
  })
}
The endpoint key endpoints.system.auth.login(token) builds the URL as: 
/api/sys/users/exchange?token=${encodeURIComponent(token)}&validForInMinutes=1440

​
Usage in Portal

ContextSource file
Magic-link / email-verification sign-insrc/states/useAuthContext.tsx (exchangeToken)
Sign-up flow — embedded checkout (/checkout)src/views/checkout/SignupUserPage.tsx
Sign-up flow — public checkout (/join)src/views/public/checkout/components/SignupForm.tsx

​
Use Cases

​
Authenticating API requests on behalf of a customer

After a server-side flow (sign-up, email verification, password reset, or magic link) issues a JWT, exchange it for a bearer token to make authenticated API requests on the customer’s behalf: 
// `rawJwt` is the token from the server-side flow (e.g., sign-up response)
const response = await httpClient.post(endpoints.system.auth.login(rawJwt))

// Use the bearer token for subsequent API calls
const { access_token, refresh_token } = response.data

httpClient.defaults.headers.common['Authorization'] = `Bearer ${access_token}`

// Now all requests are authenticated as the customer
await httpClient.get('/api/coworkers/me')
The returned access_token is valid for the duration specified in expires_in (default 24 hours). Use POST /api/token with grant_type=refresh_token to renew it before expiration.

​
Error Responses

​
400 Bad Request
error
The token parameter is missing, malformed, or has already been used. The JWT issued by Nexudus flows is single-use and expires quickly.
​
401 Unauthorized
error
The JWT signature is invalid or it was issued for a different Nexudus space.
MethodEndpointDescription
POST/api/tokenExchange a customer’s email and password for a bearer token
POST/api/sys/users/token/refreshObtain a new bearer token using a refresh token
GET/api/sys/users/impersonateIssue an impersonation token for a specific customer
POST/api/sys/users/startPasswordResetTrigger the password-reset email (returns a JWT for this flow)
POST/api/sys/users/completePasswordResetComplete password reset and exchange the resulting JWT