API clients and tokens

Quick answer

Create API clients in Settings → API access. Each client has its own scopes and generates a client secret (shown once). Exchange the client ID and secret for a short-lived Bearer token at POST /api/v1/oauth/token. Tokens expire after 1 hour; request a new one as needed.

Creating an API client

1. 1

   Open Settings → API access

   From your dashboard, go to Settings and click the API access tab.

2. 2

   Click Add client

   Give the client a descriptive name (for example, 'My CRM sync' or 'Zapier').

3. 3

   Choose scopes

   Select only the scopes your integration needs. Fewer scopes means less exposure if a token is compromised.

4. 4

   Save and copy the secret

   Click Save. The client secret is shown exactly once — copy it immediately and store it securely (a password manager or secrets vault). It cannot be retrieved again.

Getting 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.

1. 1

   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.

2. 2

   Read the response

   You receive { access_token, token_type: "Bearer", expires_in: 3600, scope }. The token is valid for 1 hour.

3. 3

   Attach to requests

   Add Authorization: Bearer <access_token> to every API request header.

4. 4

   Refresh when expired

   When a request returns 401 invalid_token, request a new token using the same client credentials.

Example token request

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" }

Managing and revoking clients

From Settings → API access you can see all your clients, which scopes they have, and when they were last used. To revoke all tokens for a client, delete the client — all outstanding tokens for it become immediately invalid.

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.