API clients and tokens
Quick answer
Admins create API clients from API access in the top bar. Name the client, tick its scopes and click Create client. Copy the secret right away, because it's shown once. Exchange the client ID and secret for a 1-hour Bearer token at POST /api/v1/oauth/token. You can rotate a client's secret, disable it, or delete it from the clients list.
On this page
Overview
Here's how to create API credentials, get access tokens, and keep them safe.
Who this is for
Developers and admins setting up an integration.
Create an API client
Open API access
Click API access in the top bar of your dashboard. Only admins see it. It opens Settings → API access.
Name the client
Under Create API client, give it a name you'll recognize, like Sample CRM sync.
Tick the scopes
Pick only what your integration needs, for example contacts:read.
Click Create client
The page shows your client ID and secret.
Copy the secret
Copy the secret
Click Copy next to the secret. It starts with cs_live_. Store it in a password manager or secrets vault.
Dismiss the banner
Click I've saved it, dismiss. You can't see the secret again after this.
Get an access token
Use the OAuth 2.0 client_credentials grant. Send your client_id and client_secret either as HTTP Basic auth (recommended) or in the JSON body.
POST to /api/v1/oauth/token
Include grant_type: client_credentials. Optionally include scope as a space-delimited string to request a subset of the client's allowed scopes. Omit scope to receive all allowed scopes.
Read the response
You receive { access_token, token_type: "Bearer", expires_in: 3600, scope }. The token is valid for 1 hour.
Attach to requests
Add Authorization: Bearer <access_token> to every API request header.
Refresh when expired
When a request returns 401 invalid_token, request a new token using the same client credentials.
Using HTTP Basic auth (client_id as username, client_secret as password): curl -s -X POST https://scramblesync.com/api/v1/oauth/token \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{"grant_type":"client_credentials"}' Response: { "access_token": "sat_…", "token_type": "Bearer", "expires_in": 3600, "scope": "contacts:read tournaments:read" }
Manage, rotate and revoke clients
The clients table lists each client's name and ID, scopes, when it was created, and its status. Each row has Rotate secret, Disable and Delete. Disabling or deleting a client stops its tokens working. Below the table, Recent API activity shows client changes, and Active tokens lists tokens that haven't expired yet.
Security best practices
- Store client secrets in a secrets manager or environment variable, never in source code or client-side JavaScript.
- Grant only the scopes your integration actually uses.
- Use one client per integration so you can revoke access individually if needed.
- Rotate secrets periodically by deleting and recreating the client.
- Never log or expose the client secret or access token in error messages or analytics.
Tips
- Make one client per integration so you can switch one off without touching the others.
- Rotate secret gives you a new secret without deleting the client.
Troubleshooting
| If you see this | Try this |
|---|---|
| I lost the secret | Click Rotate secret on that client to get a new one, then update your integration. |
| I don't see API access | Only admins see it. Ask an admin in your organization. |
Frequently asked questions
How long do access tokens last?
Access tokens expire after 1 hour (3600 seconds). Request a new token from /api/v1/oauth/token using your client credentials when needed.
Can I have multiple clients?
Yes. You can create as many clients as you need. Each client has its own scopes and secret, so different integrations can be managed and revoked independently.
Can I request only some of my client's scopes in a token?
Yes. Pass a space-delimited scope parameter when requesting a token (for example, scope=contacts:read). The token will carry only those scopes (they must be a subset of the client's allowed scopes). Omit scope to receive all allowed scopes.
What if I lose the client secret?
Click Rotate secret on the client. You'll get a new secret, shown once. Update your integration with it.
