POST

api

sys

users

exchange

Exchange JWT

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));

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

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.

number

required

Lifetime of the issued bearer token in minutes. The portal passes 1440 (24 hours) for standard sign-in sessions.

Response

string

Bearer token to include in the Authorization header of all subsequent authenticated requests.

string

Token scheme. Always bearer.

number

Lifetime of the bearer token in seconds.

string

Token used to obtain a new bearer token after it expires without requiring the customer to re-authenticate.

Examples

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

error

The token parameter is missing, malformed, or has already been used. The JWT issued by Nexudus flows is single-use and expires quickly.

error

The JWT signature is invalid or it was issued for a different Nexudus space.

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

Refresh JWT access tokenRefresh the current user JWT access token with an optional custom validity period.

Exchange JWT

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));

{
  "token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>",
  "400 Bad Request": {},
  "401 Unauthorized": {}
}

​Exchange JWT

​Authentication

​Query Parameters

​Response

​Examples

​Exchange a JWT after sign-up

​TypeScript Integration

​Usage in Portal

​Use Cases

​Authenticating API requests on behalf of a customer

​Error Responses

​Related Endpoints

Exchange JWT

Authentication

Query Parameters

Response

Examples

Exchange a JWT after sign-up

TypeScript Integration

Usage in Portal

Use Cases

Authenticating API requests on behalf of a customer

Error Responses

Related Endpoints