Skip to main content

Authentication

All Coolset API endpoints require authentication using Bearer tokens.

Getting Your API Token​

  1. Log in to your Coolset account
  2. Navigate to Settings → API Tokens
  3. Click Generate New Token
  4. Copy and securely store your token
Important

Treat your API tokens like passwords. Never share them or commit them to version control.

Using Your Token​

Include your token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

Example Request​

curl -X GET https://developers.coolset.com/api/accounts/user-config/ \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

In JavaScript​

const response = await fetch('https://developers-scranton.coolset.com/api/orders/', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

In Python​

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://developers-scranton.coolset.com/api/orders/',
    headers=headers
)

data = response.json()

Token Security Best Practices​

✅ Do's​

  • Store tokens in environment variables
  • Use separate tokens for development and production
  • Rotate tokens regularly
  • Revoke unused or compromised tokens immediately
  • Use HTTPS for all API requests

❌ Don'ts​

  • Never commit tokens to version control
  • Don't share tokens via email or chat
  • Avoid hardcoding tokens in your application
  • Don't expose tokens in client-side code
  • Never log tokens in application logs

Token Scopes & Permissions​

Tokens inherit the permissions of the user who created them. Ensure your API token has the appropriate access:

ScopePermissions
ReadView data across all endpoints
WriteCreate and update resources
AdminFull access including user management

Multi-Company Access​

If you have access to multiple companies/workspaces:

  1. Each token is associated with a specific company
  2. Switch companies in the UI before generating tokens
  3. Or use the /accounts/workspaces/ endpoint to manage context

Token Expiration​

  • API tokens do not expire automatically
  • Tokens remain valid until manually revoked
  • We recommend rotating tokens every 90 days

Revoking Tokens​

To revoke a token:

  1. Go to Settings → API Tokens
  2. Click Revoke next to the token
  3. The token becomes immediately invalid
tip

Generate separate tokens for each integration or service. This makes it easier to revoke access without affecting other services.

Authentication Errors​

401 Unauthorized​

Cause: Missing or invalid token

{
  "detail": "Authentication credentials were not provided."
}

Solution: Verify your token is correct and properly formatted in the Authorization header.

403 Forbidden​

Cause: Valid token but insufficient permissions

{
  "detail": "You do not have permission to perform this action."
}

Solution: Check your user role and token permissions.

Next Steps​