Authentication
The Coolset API authenticates with API keys. You create them yourself in the Coolset app and send them in the Authorization header with the ApiKey scheme on every request:
Authorization: ApiKey gc_...
Create an API key
API keys live on your My account page in the Coolset app, under API keys. Any user can create keys for themselves.
Sign in to the Coolset app, open My account and scroll to API keys. Any user can create keys for themselves.
The full key is shown only once, when you create it. Coolset stores a hash, not the key, so nobody can show it to you again. If you lose a key, revoke it and create a new one.
Choose a scope
Every key acts as you, with the same role and permissions you have in the app. If you can't do something in the app, the key can't either. The scope decides which workspace the key's requests go to:
User key
Scope option: You, follows your active workspace
Acts as you in whichever workspace you have open. Switch workspace in the app and the key follows.
Good for scripts you run yourself, notebooks and AI assistants.
Workspace key
Scope option: This workspace only
Pinned to the workspace that was open when you created it. Switching in the app has no effect.
Good for integrations, ERP syncs and anything that runs on a server.
| Scope | Shown in the app as | Requests go to |
|---|---|---|
user | You, follows your active workspace | The workspace you have open in the app. Switch workspace and the key follows. |
workspace | This workspace only | The workspace that was open when you created the key, always. |
Use a workspace key for integrations and anything that runs unattended, so a workspace switch in the app can never redirect its writes. Use a user key for scripts you run yourself across several workspaces.
Choose an expiration
| Option | Notes |
|---|---|
| 30 days | |
| 6 weeks | The default |
| 90 days | |
| 1 year | |
| No expiration | Only for keys you rotate yourself |
When a key expires, requests with it return 401 with Invalid or expired API key. The Expires column on My account shows when each key stops working, so you can create a replacement in time.
Use your key
Store the key in an environment variable or your secret manager, never in code:
export COOLSET_API_KEY="gc_..."
cURL
curl https://developers.coolset.com/api/accounts/users/me/ \
-H "Authorization: ApiKey $COOLSET_API_KEY"
JavaScript
const response = await fetch(
'https://developers-scranton.coolset.com/api/orders/?order_action=buying',
{ headers: { Authorization: `ApiKey ${process.env.COOLSET_API_KEY}` } },
);
const data = await response.json();
Python
import os
import requests
response = requests.get(
"https://developers-scranton.coolset.com/api/orders/",
params={"order_action": "buying"},
headers={"Authorization": f"ApiKey {os.environ['COOLSET_API_KEY']}"},
)
data = response.json()
The same key works on every Coolset API host. See base URLs.
Manage your keys
My account lists your active keys, grouped into User keys and Workspace keys. For each key you see its name, the first characters of the key, its scope, when it was created, when it was last used and when it expires.
Revoke a key
Click the trash icon next to the key and confirm. The key stops working immediately on every API host, and requests with it return 401. Revoking can't be undone.
Revoke a key when:
- the integration that used it is retired,
- Last used shows it hasn't been used for a long time, or
- you think it may have leaked.
Rotate a key
To replace a key without downtime:
- Create a new key with the same scope.
- Deploy the new key to your integration.
- Check that Last used on the new key updates.
- Revoke the old key.
Create a separate key for each integration and name it after what uses it, for example ERP sync or Data warehouse export. You can then revoke one integration's access without affecting the others.
If a key leaks
Revoke it on My account straight away, then create a replacement. If you think it was used by someone else, email support@coolset.com with the key's name and the first characters shown in the Key column. Never send the full key.
Security best practices
Do
- Store keys in environment variables or a secret manager
- Use separate keys for development and production
- Pick the shortest expiration that works for you
- Revoke unused or compromised keys immediately
- Use HTTPS for all API requests
Don't
- Commit keys to version control
- Share keys by email or chat
- Hardcode keys in your application
- Expose keys in browser or mobile code
- Write keys to application logs
Authentication errors
401 Unauthorized
Cause: The key is missing, mistyped, expired or revoked.
{
"detail": "Invalid or expired API key"
}
Solution: Check that the header is exactly Authorization: ApiKey gc_..., and that the key is still listed on My account. A response of Invalid JWT Credentials means the key was sent with the wrong scheme, for example Bearer. The WWW-Authenticate: Bearer header on 401 responses does not apply to API keys.
403 Forbidden
Cause: The key is valid, but your role in the workspace doesn't allow the action.
{
"detail": "You do not have permission to perform this action."
}
Solution: Keys have the same permissions as you. Ask a workspace owner to change your role, or use a key created by someone who has the access.
