Private Integration Tokens

A Private Integration Token (PIT) is a long-lived credential scoped to a single SMBcrm account/location. It’s built for server-to-server integrations, automations, dashboards, and AI agents: anywhere your own backend needs to call the API without a person logging in.

What a PIT is

A PIT is tied to one SMBcrm account/location from the moment you create it. There’s no authorization redirect and no user session to expire. You create the token, copy it, and start making requests. That makes it the right choice whenever there’s no end user in the loop:

Server-to-server integrations and internal tools that only ever talk to your account
Scheduled jobs and batch syncs: nightly imports, backfills, reporting
Internal dashboards and admin tools built for your own team
AI agents and MCP clients that read or write your account’s data on a schedule or on demand

PIT vs OAuth

Use whichever matches who is making the request:

Aspect	Private Integration Token	OAuth
Use it when	Your own backend, script, or agent calls your own account	A user authorizes your app to act on their account
Setup	Create once in the SMBcrm app	Authorization redirect, then a token exchange
Lifetime	Long-lived. Doesn’t refresh itself; changes only when you rotate or delete it (rotate every 90 days)	Access token expires after about 24 hours; refresh with a refresh token
Best for	Internal tools, automations, AI agents, dashboards	Apps that other people’s accounts install and authorize

If every request targets your own account and you control the server making them, a PIT is less work than OAuth. There’s no redirect flow or refresh-token handling to build. If you’re building something that other SMBcrm accounts will need to authorize for themselves, see OAuth (account access) instead.

A PIT gives you API access only. It doesn’t subscribe you to event webhooks. To have events pushed to your server, add a Custom Webhook action to a workflow (see Webhooks).

Create a PIT

Private Integration Tokens are created in the SMBcrm app, not through the API. There’s no endpoint that issues one for you.

Open the SMBcrm account you want the token to act on, then open Settings.
Go to Private Integrations.
Click Create new Integration, then enter a name and a description. Pick a name you’ll recognize later (“Nightly contact sync” is more useful than “Token 1”). The description helps your team see what the integration is for.
Select the scopes the integration needs, and only those.
Copy the token right away.

Use a PIT

Send a PIT exactly like an OAuth access token: as a bearer token in the Authorization header, alongside the required Version header. See Base URL & Headers for the full request shape.

GET/contacts/{contactId}

Fetch a contact using a Private Integration Token.

scope contacts.readonlyauth Location token or PIT

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

{
  "contact": {
    "id": "<contact_id>",
    "locationId": "<location_id>",
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "jordan@example.com"
  }
}

The API treats a PIT and an OAuth access token the same way. There’s no separate header or query parameter for it. The only difference is how you obtained the token.

Scopes

A PIT only grants the scopes you select for it. It can’t reach anything outside that list, even if your account has broader data. Grant the least privilege the integration needs: a job that only reads contact data needs contacts.readonly, not contacts.write or scopes for parts of the account it never touches. If you build a feature later that needs more access, edit the private integration and update its scopes rather than over-provisioning up front.

To edit an integration, open Settings, then Private Integrations. Open the three-dot menu on the integration and choose Edit. Change the name or description if you want, click Next, adjust the scopes, and click Update. Editing doesn’t change the token. The existing token keeps working with the new scopes, so you don’t need to redeploy.

Rotate a PIT

Rotate each PIT every 90 days. Rotation issues a new token for the same integration. You can rotate with an overlap window, so your app has time to switch over.

Open Settings, then Private Integrations, and click the integration.
Click Rotate and expire this token later.
Click Continue on the warning.
Copy the new token and update your app. Like the original, the new token is shown only once.

For 7 days, both the old and the new token work. After 7 days, the old token expires. During that window you can:

Click Cancel rotation if your app needs more time.
Click Expire Now once your app is using the new token.

If a token has leaked, don’t use the overlap window. See Security.

Security

A PIT carries the same reach as a password to your account’s data, so treat it like one:

Store it as a server-side environment variable or secret. Never put it in client-side code or a mobile app, and never commit it to a repo.
Don’t paste it into logs, tickets, chat messages, or screenshots.
If a contractor needs access, create a dedicated PIT with only the scopes they need and share it only through a trusted channel.
If a token leaks, open the integration under Settings, then Private Integrations, and choose Rotate and expire this token now. This issues a replacement and stops the old token immediately, so requests that use the old token fail. Don’t choose Rotate and expire this token later after a leak, because that keeps the old token valid for 7 days.
When you retire an integration, delete it so no unused token stays valid. Open the three-dot menu on the integration under Settings, then Private Integrations, and choose Delete.

Full guidance on where tokens tend to leak and how to protect them is in Token Safety.

OAuth (account access): authorize an app to act on someone else’s SMBcrm account.
Scopes: the full list of permissions a token can request.
Token Safety: storing, rotating, and protecting tokens.
Base URL & Headers: the request shape every endpoint expects.