OAuth2 Clients

Use this topic for manage scoped server-to-server clients.

Before you start

  • Use the correct company and an active account with permission for this workflow.

Where to go

Integrations → OAuth2 Clients

Audience

Business owners and active company admins responsible for server-to-server integrations.

Permissions

  • Company owners and active company admins may create or revoke OAuth2 clients.
  • Treat every OAuth2 client secret as a server-side secret; never place it in browser code, mobile apps, source control, logs, or callback payloads.
  • The client secret is revealed once after creation. Store it immediately in a server-side secret manager; if it is lost or exposed, revoke the client and create a replacement.
  • Use least privilege: select only the scopes the integration needs.

Actions

Create OAuth2 client
Use Create OAuth2 client to support manage scoped server-to-server clients.
Revoke OAuth2 client
Use Revoke OAuth2 client to support manage scoped server-to-server clients.

Statuses

Active
The record is currently active.
Revoked
The record is currently revoked.

Workflow

  1. Open OAuth2 Clients, create a client, and select only the required subset of catalog:write, analytics:read, boost:read, analytics:write, and boost:write.
  2. Copy the reveal-once client secret into a server-side secret manager, then close the reveal dialog.
  3. From your server, POST to https://api.crewlogix.app/v1/oauth/token with grant_type=client_credentials, the client ID, client secret, and its assigned space-delimited scopes.
  4. Use the returned Bearer access token for only its assigned scopes; revoke and replace the client if its secret is exposed.
  5. The client_credentials flow does not use a browser redirect or OAuth callback. Configure any separate CrewLogix event callback as a public HTTPS URL and never include credentials in its payload.
  6. For planned rotation, create and deploy a replacement client first, confirm token requests use it, then revoke the old client.
  7. For a read-only first request, assign analytics:read only and GET /v1/analytics/<vendor-id>/daily with the returned Bearer access_token. The vendor ID must match your client’s company; no query parameters are required.
  8. Expect a 200 analytics response for the authorized company. Honor expires_in, currently 900 seconds; obtain another client_credentials token when needed. No refresh token is issued.

Expected outcome

Read the current saved state in the workspace after the permitted action; Help does not perform or verify the action.

Troubleshooting

The token endpoint returns invalid_client
Confirm the client is active and the reveal-once client secret is correct; revoke and replace a lost or exposed client
The token endpoint returns invalid_scope or an API call returns 403
Use only scopes assigned to the active client and recreate it with the smallest required supported scope set
An OAuth2 client secret appears in source control, logs, browser code, or a callback payload
Revoke the exposed client immediately, remove the leaked value, create a replacement, and store its secret only on the server
unsupported_grant_type
Send grant_type=client_credentials using the documented form request; this is not a browser authorization-code flow.

Developer examples

Request a vendor token

curl -X POST https://api.crewlogix.app/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>" \
  --data-urlencode "scope=analytics:read"

Read company analytics

curl -X GET https://api.crewlogix.app/v1/analytics/<vendor-id>/daily \
  -H "Authorization: Bearer <access-token>"