OAuth (account access)

Use OAuth when you’re building an integration that a SMBcrm user authorizes to act on their account/location. After the user approves, you exchange an authorization code for a short-lived access token and a refresh token you use to get new access tokens.

Just automating your own account?

If no separate user needs to authorize access and you’re building for your own account, a Private Integration Token is simpler and skips the authorization flow entirely. Reach for OAuth when other users grant access to their account.

The flow

1. Send the user to an authorization URL for SMBcrm with your client_id, the scopes you need, and your redirect_uri.
2. The user approves access to their account/location. SMBcrm redirects back to your redirect_uri with a one-time code.
3. Your server exchanges the code for an access_token and refresh_token.
4. You call the API with Authorization: Bearer <access_token>, refreshing when it expires.

Getting OAuth credentials

OAuth needs a client_id and client_secret issued for your integration, plus one or more registered redirect_uris. Arrange these with SMBcrm for your account; the authorization URL you send users to comes with them.

Exchange the code for a token

Do this on your server — the client_secret must never reach the browser. Set user_type=Location to receive a token scoped to a single account/location.

cURL

curl -X POST https://services.smbcrm.com/oauth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "client_secret=<client_secret>" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<authorization_code>" \
  --data-urlencode "user_type=Location" \
  --data-urlencode "redirect_uri=https://your-app.example.com/oauth/callback"

Node.js

const body = new URLSearchParams({
  client_id: process.env.SMBCRM_CLIENT_ID,
  client_secret: process.env.SMBCRM_CLIENT_SECRET,
  grant_type: 'authorization_code',
  code: authorizationCode,
  user_type: 'Location',
  redirect_uri: 'https://your-app.example.com/oauth/callback',
});

const res = await fetch('https://services.smbcrm.com/oauth/token', {
  method: 'POST',
  headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
  body,
});
const token = await res.json();

200 OK

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 86399,
  "refresh_token": "<refresh_token>",
  "scope": "contacts.readonly contacts.write",
  "locationId": "<location_id>",
  "userType": "Location"
}

Store the refresh_token on your server and note the returned locationId, which is the account/location this token acts on.

Refresh the access token

Access tokens expire. Use the refresh_token to get a new one without sending the user back through authorization.

curl -X POST https://services.smbcrm.com/oauth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "client_secret=<client_secret>" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=<refresh_token>" \
  --data-urlencode "user_type=Location"

The response matches the shape above, with a fresh access_token and usually a new refresh_token. Store the latest one.

Use the access token

curl https://services.smbcrm.com/contacts/<contact_id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Version: v3"

Request only the scopes you need, and keep every secret on your server. See Token Safety.