Refresh access token

1 min

POST

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

Exchange a valid refresh token for a new access token and refresh token pair.

Token Rotation: Each refresh operation issues a new refresh token and invalidates the previous one. This limits the window of exposure if a refresh token is compromised.

Tenant Switching: Optionally switch to a different authorized tenant by including the tenant parameter. The new tenant must be in the user's list of authorized tenants.

Body Parameters

bodyRefreshRequestrequired
Description
Refresh token for obtaining new access token
- refreshTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  Description
  Valid refresh token from previous login or refresh
- tenantstring
  Example
  tenant-456
  Description
  Optional tenant to switch to during refresh. Must be in the user's list of authorized tenants.
- sitestring
  Example
  site-123
  Description
  Optional site to switch to during refresh. Must be in the user's list of authorized sites for the target tenant.

Responses

200Token refresh successful

AuthResponse
Example
```
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
```
Description
Successful authentication response containing tokens
- accessTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
  Description
  JWT access token for API authorization.
  
  Include in API requests as: Authorization: Bearer <accessToken>
  
  Claims:
  
  sub: User ID (UUID)
  
  type: Token type (consumer/management)
  
  roles: List of role identifiers
  
  tenant: Active tenant ID
  
  iat: Issued at (Unix timestamp)
  
  exp: Expiration (Unix timestamp)
  
  iss: Issuer (auth-svc)
- refreshTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
  Description
  Refresh token for obtaining new access tokens.
  
  Store securely (e.g., httpOnly cookie or secure storage). Use with /api/v1/auth/refresh when access token expires.
- expiresIninteger<int64>required
  Example
  3600
  Description
  Access token validity duration in seconds
  Format
  int64
- tokenTypestringrequired
  Example
  Bearer
  Description
  Token type (always "Bearer")

400Invalid request body

ErrorResponse
Example
```
{
  "error": "invalid_request",
  "message": "Failed to read request body",
  "code": "BAD_REQUEST"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

401

Invalid, expired, or revoked refresh token

ErrorResponse
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

403Unauthorized tenant switch

ErrorResponse
Example
```
{
  "error": "unauthorized_tenant",
  "message": "User is not authorized for tenant: tenant-xyz",
  "code": "UNAUTHORIZED_TENANT"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

500Internal server error

ErrorResponse
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

curl

curl --request POST \
     --url https://api.upstartcommerce.com/api/v1/auth/refresh \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/api/v1/auth/refresh", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/api/v1/auth/refresh")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/api/v1/auth/refresh"

payload = json.dumps({
   "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Token refresh successful
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

400

// Invalid request body
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

401

// Invalid, expired, or revoked refresh token
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

GENERATED

// Invalid, expired, or revoked refresh token
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

invalidToken

// Invalid token
{
  "error": "unauthorized",
  "message": "Invalid refresh token",
  "code": "UNAUTHORIZED"
}

expiredToken

// Expired token
{
  "error": "unauthorized",
  "message": "Refresh token has expired",
  "code": "UNAUTHORIZED"
}

revokedToken

// Revoked token
{
  "error": "unauthorized",
  "message": "Refresh token has been revoked",
  "code": "UNAUTHORIZED"
}

403

// Unauthorized tenant switch
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

500

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

GENERATED

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

tokenGenerationFailed

// Token generation failed
{
  "error": "internal_error",
  "message": "Token generation failed",
  "code": "INTERNAL_SERVER_ERROR"
}

serviceError

// Upstream service error
{
  "error": "internal_error",
  "message": "Failed to communicate with authentication backend",
  "code": "INTERNAL_SERVER_ERROR"
}