OAuth 2.0 and client credentials

MyCRM uses the OAuth 2.0 client credentials flow for server-to-server integrations. Your application authenticates as itself; a user does not log in through a browser or approve an authorisation-code redirect for this flow.

The moving parts

Value	Meaning
Client ID	Identifies the application
Client secret	Authenticates the application; keep it server-side
Scope	Space-separated capabilities requested for this token
Access token	Short-lived credential sent to the API
expires_in	Token lifetime in seconds returned by the token endpoint
UserId	Adviser context on API requests; separate from OAuth authentication

Request an access token

Use the complete authentication URL provided during onboarding. The sample client sends the client ID and secret as HTTP Basic authentication, with the grant and scopes in a form-encoded body:

curl --request POST "$AUTH_URL" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "scope=$SCOPES"

The samples README also illustrates credentials in the form body. Use the method supported for your issued client, and do not send multiple client authentication methods in one request.

An illustrative response is:

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.contacts.read"
}

The value 3600 is an example, not a fixed MyCRM lifetime. Use the returned expires_in.

Use and reuse the token

Send Authorization: Bearer {access_token} on API requests. Cache the token with its expiry, allow a small expiry margin, and coordinate refreshes so concurrent requests do not all request new tokens at once. With client credentials, request another access token using the same grant; do not assume a refresh token is issued.

If a token is rejected, refresh it once where appropriate and retry a safe request. A persistent 401 needs investigation. A 403 or beta 423 is not normally fixed by repeatedly requesting new tokens.

Keep credentials on the server

Do not embed a client secret in a website, browser application, mobile binary or shared Postman export. Redact secrets, bearer tokens and sensitive payloads from logs. Rotate credentials through the agreed support process and deploy updated secrets to each application instance.

Scopes constrain operations, not which records are owned by an organisation. Continue with scopes, data access and request headers.

For the protocol background, see OAuth 2.0 client credentials.