Exchange JWT

Exchange a short-lived JWT issued by a Nexudus server-side flow for a bearer token that authenticates subsequent API requests.

POST /api/sys/users/exchange

Exchange JWT

cURL

curl --request POST \
  --url https://spaces.nexudus.com/api/sys/users/exchange \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://spaces.nexudus.com/api/sys/users/exchange"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://spaces.nexudus.com/api/sys/users/exchange', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "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

Context	Source file
Magic-link / email-verification sign-in	src/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.

Related Endpoints

Method	Endpoint	Description
POST	/api/token	Exchange a customer’s email and password for a bearer token
POST	/api/sys/users/token/refresh	Obtain a new bearer token using a refresh token
GET	/api/sys/users/impersonate	Issue an impersonation token for a specific customer
POST	/api/sys/users/startPasswordReset	Trigger the password-reset email (returns a JWT for this flow)
POST	/api/sys/users/completePasswordReset	Complete password reset and exchange the resulting JWT