Skip to main content
Refresh a bearer token
curl --request POST \
  --url https://spaces.nexudus.com/api/token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'client_id: <client_id>' \
  --data '
{
  "grant_type": "<string>",
  "refresh_token": "<string>"
}
'
{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>",
  "400 Bad Request — unsupported_grant_type": {},
  "400 Bad Request — invalid_grant": {}
}

​
Refresh a bearer token

Uses a refresh token to obtain a new access token and refresh token without requiring the customer to re-enter their password. This is useful when the access token has expired but you want to maintain the customer’s session.
Unlike most Nexudus API endpoints, this request must be encoded as application/x-www-form-urlencoded, not application/json. Sending a JSON body will result in an unsupported_grant_type error.

​
Authentication

No authentication required. This endpoint uses the refresh token itself as the credential.

​
Request Body

​
grant_type
string
required
Must be refresh_token to use the refresh token grant flow.
​
refresh_token
string
required
The refresh token previously received from the sign-in endpoint.

​
Headers

​
client_id
string
required
The client identifier that was used when obtaining the bearer token. If the client_id was provided during sign-in, use that value. If client_id was omitted during sign-in, use the customer’s email address (which defaults to the client_id automatically).

​
Response

​
access_token
string
New 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 new access token in seconds.
​
refresh_token
string
New refresh token to use for subsequent refresh operations. The previous refresh token is invalidated.

​
Examples

​
Successful token refresh

POST /api/token
Content-Type: application/x-www-form-urlencoded
client_id: jane.doe@example.com

grant_type=refresh_token&refresh_token=8xLOxBtZp8

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "9yMPyCuQr9"
}

​
TypeScript Integration

import { type AxiosResponse } from 'axios'
import qs from 'qs'
import { type AuthToken } from '@/states/useAuthContext'

const data = {
  grant_type: 'refresh_token',
  refresh_token: session.refreshToken,
}

const res: AxiosResponse<AuthToken> = await httpClient.post('/api/token', qs.stringify(data), {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'client_id': session.clientId, // or email if client_id was omitted during sign-in
  },
})

if (res.data.access_token) {
  saveSession({ tokenResponse: res.data, remember: values.rememberMe })
}

​
Error Responses

​
400 Bad Request — unsupported_grant_type
error
The grant_type field is missing or the body was not encoded as application/x-www-form-urlencoded.
​
400 Bad Request — invalid_grant
error
The refresh token is invalid, expired, or has already been used. The error_description field contains a human-readable reason.
MethodEndpointDescription
POST/api/token(this endpoint) Exchange credentials for a bearer token
POST/api/sys/users/token/refreshGet a short-lived server-side JWT for authenticated links