Create business-scoped access token

Create a business-scoped JWT token for accessing business-specific endpoints. Requires a valid partner (unscoped) Bearer token in the Authorization header. Use the BearerUnscoped option in Swagger UI.

POST /v1/platform/{business_id}/oauth2/token

Create business-scoped access token

cURL

curl --request POST \
  --url https://sandbox.thredfi.com/v1/platform/{business_id}/oauth2/token/ \
  --header 'Authorization: Bearer <token>'

200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhMWIyYzNkNC01Njc4LTkwYWItY2RlZi0xMjM0NTY3ODkwYWIiLCJidXNpbmVzc19pZCI6IjNjOTBjM2NjLTBkNDQtNGI1MC04ODg4LThkZDI1NzM2MDUyYSIsImlhdCI6MTcwOTgyMTIwMCwiZXhwIjoxNzA5ODI0ODAwfQ.example",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "business_access",
  "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

What is a Business-Scoped Token?

A business-scoped token is a JWT that grants access to a specific business’s data. It’s required for endpoints that operate on business-level resources (customers, invoices, bills, etc.).

Why Two Types of Tokens?

Partner Token (Unscoped):

• Obtained from /oauth2/token/ using your Partner UUID + API Key
• Used for partner-level operations: listing businesses, creating new businesses
• Can access multiple businesses you own
• Limited scope - cannot access business-specific resources

Business Token (Scoped):

• Obtained from /{business_id}/oauth2/token/ using a partner token
• Used for business-specific operations: managing customers, invoices, bills, payments
• Locked to one business - can only access that business’s data
• Required for most API endpoints

When Do You Need This?

Use business-scoped tokens for:

• Managing customers for a specific business
• Creating invoices or bills
• Processing payments
• Any endpoint with /businesses/{business_id}/ in the path

Use partner tokens for:

• Listing all businesses you manage
• Creating new businesses
• Partner-level reporting

How It Works

Step 1: Get partner token (unscoped)

# First, get your partner-level token
curl -X POST https://sandbox.thredfi.com/v1/platform/oauth2/token/ \
  -H "Authorization: Basic $(echo -n 'PARTNER_UUID:API_KEY' | base64)" \
  -d "grant_type=client_credentials"

# Response: { "access_token": "partner_token_here..." }

Step 2: Exchange for business-scoped token

# Then, get a business-specific token
curl -X POST https://sandbox.thredfi.com/v1/platform/BUSINESS_ID/oauth2/token/ \
  -H "Authorization: Bearer partner_token_here"

# Response: { "access_token": "business_scoped_token_here..." }

Step 3: Use business token for operations

# Now you can access business resources
curl https://sandbox.thredfi.com/v1/platform/businesses/BUSINESS_ID/customers/ \
  -H "Authorization: Bearer business_scoped_token_here"

Code Examples

Python

import requests
import base64

# Step 1: Get partner token
partner_uuid = "123e4567-e89b-12d3-a456-426614174000"
api_key = "sk_live_abc123xyz789"
credentials = f"{partner_uuid}:{api_key}"
encoded = base64.b64encode(credentials.encode()).decode()

partner_response = requests.post(
    "https://sandbox.thredfi.com/v1/platform/oauth2/token/",
    headers={"Authorization": f"Basic {encoded}"},
    data={"grant_type": "client_credentials"}
)
partner_token = partner_response.json()["access_token"]

# Step 2: Get business-scoped token
business_id = "456e7890-e89b-12d3-a456-426614174111"
business_response = requests.post(
    f"https://sandbox.thredfi.com/v1/platform/{business_id}/oauth2/token/",
    headers={"Authorization": f"Bearer {partner_token}"}
)
business_token = business_response.json()["access_token"]

# Step 3: Use business token to access resources
customers = requests.get(
    f"https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/customers/",
    headers={"Authorization": f"Bearer {business_token}"}
)
print(customers.json())

Security Note

Business-scoped tokens are more secure for business operations because:

• They can only access one specific business
• If compromised, the blast radius is limited to that single business
• They can be revoked independently without affecting other businesses

Token Lifecycle

1. Partner token is long-lived (typically 24 hours)
2. Business token is also long-lived (typically 24 hours)
3. Both can be refreshed by re-authenticating
4. Store securely and never expose in client-side code

Authorizations

PartnerJWTBasicAuthBearerUnscopedBearerBusinessScoped

Authorization · string · header · required

Partner-level JWT token (unscoped). Token payload includes partner_id. Business access is validated via partner ownership. Format: Bearer <your-jwt-token>

Use this for: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses.

Path Parameters

business_id · string<uuid> · required

Response

200

application/json

Serializer for business-scoped token response

access_token · string · required

Business-scoped JWT Bearer token

expires_in · integer · required

Token expiration time in seconds

scope · string · required

Token scope (always 'business_access')

business_id · string<uuid> · required

ID of the business this token is scoped to

token_type · string · default: Bearer

Token type (always 'Bearer')