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

Note

A PIT is scoped to one SMBcrm account/location. If you work with more than one account, create a separate PIT in each. A single PIT never spans accounts.

PIT vs OAuth

Use whichever matches who’s actually 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, until you revoke it	Access token expires; 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.

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.

1. Log in to your SMBcrm account and open Settings.
2. Find the section for private integrations (it may be grouped with API keys or other integration settings, depending on your account).
3. Create a new token, give it a name you’ll recognize later (“Nightly contact sync” is more useful than “Token 1”), and select the scopes it needs.
4. Save it and copy the token right away.

Copy it now

The token is shown once, at creation. SMBcrm doesn’t display it again afterward. If you lose it, revoke it and create a new one.

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"

200 OK

{
  "contact": {
    "id": "<contact_id>",
    "locationId": "<location_id>",
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "[email protected]"
  }
}

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

Tip

Call the API from your server, not the browser. A PIT is a long-lived secret. Anyone who opens dev tools on a page that holds one can read it and use it. See Token Safety.

Scopes

A PIT only grants the scopes you select when you create it. It can’t reach anything outside that list, even if your account has broader data. Grant the least privilege the integration actually 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 (or create a new one) and update its scopes rather than over-provisioning up front.

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 in client-side code, a mobile app, or committed to a repo.
• Don’t paste it into logs, tickets, chat messages, or screenshots.
• If a token leaks, revoke it in the SMBcrm app immediately and create a new one. Requests using the old token stop working the moment it’s revoked.

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

Related

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