Get available tenants for current session

1 min

GET

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

Returns the current active tenant and list of all authorized tenants for the user associated with the provided refresh token.

Use this endpoint to populate a tenant switcher UI.

Authentication: Provide the refresh token via either:

Authorization: Bearer <refresh-token> header
refresh_token query parameter

Query Parameters

refresh_tokenstring
Example
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Description
Alternative way to provide refresh token (if not using Authorization header)

Header Parameters

Authorizationstring
Example
Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Description
Bearer token containing the refresh token
Pattern
^Bearer .+$

Responses

200Tenant information retrieved successfully

TenantInfoResponse
Example
```
{
  "currentTenant": "tenant-123",
  "availableTenants": [
    "tenant-123",
    "tenant-456",
    "tenant-789"
  ]
}
```
Description
Information about user's tenant access
- currentTenantstringrequired
  Example
  tenant-123
  Description
  Currently active tenant for this session
- availableTenantsstring[]required
  Example
```
[
  "tenant-123",
  "tenant-456",
  "tenant-789"
]
```
  Description
  List of all tenants the user is authorized to access

400Refresh token not provided

ErrorResponse
Example
```
{
  "error": "invalid_request",
  "message": "Refresh token required via Authorization header or refresh_token query parameter",
  "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

401Invalid or revoked refresh token

ErrorResponse
Example
```
{
  "error": "unauthorized",
  "message": "Invalid or revoked refresh token",
  "code": "UNAUTHORIZED"
}
```
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 GET \
     --url https://api.upstartcommerce.com/api/v1/auth/tenants \
     --header 'accept: application/json'

javascript

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

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/api/v1/auth/tenants", 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/tenants")

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

request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"

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

python

import requests
import json

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

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

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

print(response.text)

200

// Tenant information retrieved successfully
{
  "currentTenant": "tenant-123",
  "availableTenants": [
    ""
  ]
}

400

// Refresh token not provided
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

401

// Invalid or revoked refresh token
{
  "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"
}