SMARTSHIFTS DEVELOPERS · INTEGRATIONS

One app. Every customer's own connection.

Register your server-side integration once. Customers click Connect SmartShifts, sign in and approve their organization and permissions. They never create their own OAuth application, API key or API signing secret.

1. Register once as the application operator

Open Platform Admin → Integration Apps using your verified platform-administrator account. Register the application's display name, exact HTTPS callback URL(s), and permitted scopes. Start with employees:read locations:read for roster and training integrations.

Save the client ID and one-time client secret in the integrating application's server-side secret manager. Never put the secret in browser code, mobile apps, URLs, source control or a customer's form. One registration serves all customers. Callback paths must match exactly. No wildcard or open-redirect callbacks. Localhost HTTP is development-only.

2. Start Connect SmartShifts

On your server, generate a random state and PKCE verifier (43–128 URL-safe characters); save them in a short-lived, single-use session tied to the signed-in customer in your application. Compute code_challenge = BASE64URL(SHA256(code_verifier)), without padding. Redirect the browser:

https://app.smartshifts.com/api/integration-oauth/authorize
  ?response_type=code
  &client_id=YOUR_APP_CLIENT_ID
  &redirect_uri=YOUR_EXACT_URL_ENCODED_CALLBACK
  &scope=employees%3Aread%20locations%3Aread
  &state=YOUR_RANDOM_SESSION_BOUND_STATE
  &code_challenge=YOUR_S256_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapp.smartshifts.com%2Fapi%2Fexternal%2Fv1

The customer must be an active organization-wide administrator. Employees, site-limited managers, inactive accounts and platform-only administrators cannot grant organization-wide workforce access. Customers explicitly choose their organization and may narrow the requested scopes. The resulting grant is valid for up to 90 days; reconnect before it expires.

3. Verify the callback and exchange the code

Your callback must validate the returned state against the signed-in customer's original session, consume it once, and handle error=access_denied. Bind the returned SmartShifts organization_id to the intended customer record; do not silently merge customers or accept an unexpected organization.

POST https://app.smartshifts.com/api/integration-oauth/token
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=RETURNED_CODE
&redirect_uri=EXACT_URL_ENCODED_CALLBACK&code_verifier=ORIGINAL_VERIFIER
{
  "access_token": "OPAQUE_ACCESS_TOKEN",
  "refresh_token": "OPAQUE_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "employees:read locations:read",
  "organization_id": "CUSTOMER_SMARTSHIFTS_ORGANIZATION_ID",
  "connection_id": "OAUTH_CONNECTION_ID"
}

Codes expire after two minutes and are single-use. PKCE is required even for confidential clients. Both client_secret_basic and client_secret_post are supported. Client-credentials grants and unattended initial customer authorization are intentionally not supported.

4. Read the existing API using Bearer authentication

GET https://app.smartshifts.com/api/external/v1/employees
Authorization: Bearer OPAQUE_ACCESS_TOKEN

GET https://app.smartshifts.com/api/external/v1/locations
Authorization: Bearer OPAQUE_ACCESS_TOKEN

Do not send X-API-Key, X-Timestamp or X-Signature with OAuth. Existing HMAC API-key integrations continue working unchanged. All REST endpoints retain their business validation, scope requirements and tenant isolation. OAuth tokens are REST-only: they cannot access MCP, browser/admin session routes, or platform administration.

Employee responses include jobTitle, jobTitles and jobTitleStatus. Access roles are not duties or certification requirements. Disclose missing or incomplete title information before proposing role-specific training. Do not infer an organization training policy.

REST endpoint and webhook reference

5. Refresh automatically and disconnect safely

POST https://app.smartshifts.com/api/integration-oauth/token
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=LATEST_REFRESH_TOKEN

Refresh tokens rotate on every use and expire after 30 days or the connection's expiry, whichever comes first. Save the new pair atomically and serialize refresh operations per customer connection. The old access token is invalidated when its refresh token is consumed. Reusing an already-consumed refresh token revokes the connection. Never blindly retry a timed-out refresh: reconcile your stored pair or ask the customer to reconnect. Tokens cannot widen consented scopes.

POST https://app.smartshifts.com/api/integration-oauth/revoke
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

token=ACCESS_OR_REFRESH_TOKEN

Customers can also revoke access in Settings → API & Webhooks → Connected apps. Disabling the application in Platform Admin blocks all its customer connections. Live organization membership is checked on every use. Secret rotation affects future token exchanges; existing access tokens last until their normal expiry unless the application or connection is disabled.

Handle 401 by refreshing once; invalid_grant requires reconnection. Treat 403 insufficient_scope as a permission denial, not a retry. Rate limits return 429; respect Retry-After. Defaults: 120 API requests per minute per connection, 600 per organization, plus IP safeguards.

6. Platform-managed partner webhooks

In Platform Admin → Integration Apps → Webhooks → Add endpoint, create up to 20 named public HTTPS receivers per partner app. Each endpoint has its own independent signing secret, event subscriptions, enablement, test ping and delivery history. For example, send employee events to a training receiver and site events to an operations receiver. Save each one-time secret in that receiver's server-side secret manager. Secrets are never returned by settings reads.

Each endpoint applies automatically to every existing or future customer who connects with the relevant read permissions. Customers do not configure endpoints or webhook signing secrets. Every delivery still requires that particular customer's active OAuth grant and the app's allowed scopes: adding another endpoint never grants access to another tenant. Webhook secrets are separate from each other and from the OAuth client secret. Existing tenant-configured webhooks continue working independently; do not subscribe to both mechanisms unless your receiver handles duplicate notifications.

Employees — employees:readSites — locations:read
employee.created
employee.updated
employee.deactivated
employee.reactivated
employee.deleted
location.created
location.updated
location.deactivated
location.reactivated
location.deleted

Site events use the location. prefix. Deactivation means a retained record became inactive; deletion means permanent removal. Status changes also produce an updated event. Creation, edits and deletion are captured transactionally at the database boundary, including changes made by screens, mobile, APIs, imports and AI tools. No-op updates that change only updated_at are ignored. An organization transfer produces a deletion for the old organization and creation for the new one. Events are not a historical backfill: perform an initial API sync after connecting.

{
  "id": "STABLE_EVENT_ID",
  "appName": "SmartShifts",
  "event": "employee.created",
  "restaurantId": "CUSTOMER_ORGANIZATION_ID",
  "organizationId": "CUSTOMER_ORGANIZATION_ID",
  "connectionId": "OAUTH_CONNECTION_ID",
  "endpointId": "PARTNER_WEBHOOK_ENDPOINT_ID",
  "timestamp": "2026-11-19T12:00:00Z",
  "data": {
    "id": "EMPLOYEE_ID",
    "employeeId": "EMPLOYEE_ID",
    "locationId": "SITE_ID",
    "status": "active",
    "isActive": true,
    "deleted": false
  }
}

Payloads contain identifiers and record status, not personnel documents, pay rates, names or contact information. Fetch employee/site details through the API using that organization's OAuth tokens. A deleted record cannot be fetched; use its identifier to reconcile your local roster. OAuth token responses include connection_id so your app can map connectionId without guessing. Both restaurantId and organizationId identify the same customer tenant. Each subscribed endpoint gets one delivery per event and organization, using the newest eligible connection. Overlapping endpoint subscriptions share the stable event id but have different delivery IDs and endpointId values.

Verify signatures and prevent replays

Capture and retain the raw request body. Use the signing secret for the exact receiving endpoint, not another endpoint's or the OAuth client secret. Prefer a distinct receiver path mapped to its secret. If you use the untrusted payload's endpointId to select a candidate key from your own allowlist, do not trust any payload field or perform business actions until signature verification succeeds. Recommended: read X-SmartShifts-Delivery-Timestamp (Unix seconds) and X-SmartShifts-Delivery-Signature (v1=HEX). Compare against HMAC-SHA256(signingSecret, deliveryTimestamp + "." + rawBody) using a constant-time comparison, and reject delivery timestamps more than five minutes old or in the future. Each retry gets a fresh delivery timestamp/signature. Persist processed payload id values to make all effects idempotent; use (endpointId, id) if each endpoint intentionally runs a separate workflow, or a shared id ledger to run a shared action only once across endpoints. Check organizationId against your stored customer grant; never accept an arbitrary tenant supplied by the caller.

For compatibility, X-SmartShifts-Signature: sha256=HEX is also HMAC-SHA256 of the raw body alone. X-SmartShifts-Timestamp is the event's original timestamp, not the delivery time; it can legitimately be old on a retry. X-SmartShifts-Event-Id matches the signed payload id. X-SmartShifts-Delivery-Id identifies the queued delivery and is stable across retries.

Delivery, shutdown and testing

Durable queued delivery is at-least-once and not guaranteed in order. Persist the notification in your own queue before returning a 2xx. Timeouts and all non-2xx responses (including redirects) retry after approximately 5 seconds, 30 seconds, 5 minutes, 30 minutes and 2 hours, up to six total attempts. The worker polls every five seconds while the API service is running; a stopped service delays delivery until it resumes, so do not scale the worker to zero when continuous delivery is required. Restarted workers resume pending work. Receiver outcomes can be uncertain after a timeout or process interruption: deduplication is required. Fetch the current API state rather than assuming events arrived in chronological order.

Before each attempt, SmartShifts rechecks the app, exact endpoint configuration, customer grant, expiry, active authorizing administrator, organization and required read scope. Disconnecting, expiry or disabling an app prevents further queued deliveries; an already in-flight HTTP request cannot be recalled. Pausing, removing, changing the URL/subscriptions or rotating an endpoint's secret cancels only that endpoint's old queued deliveries, never another endpoint's. Name-only edits preserve its queue. Secret rotation invalidates the previous secret immediately; update the receiver and reconcile through the API after delivery-setting changes. Removed endpoints have their secrets erased while delivery history remains stored. Platform Admin shows the last 50 deliveries per current endpoint, attempts, HTTP status and failures; failed final attempts are not silently retried forever.

Compatibility and deployment: Existing single-endpoint settings, encrypted secrets and delivery history migrate without rotating the secret. Historical payloads may not contain endpointId; use the original receiver path's secret. Existing management URLs ending in /webhooks, /webhooks/rotate-secret and /webhooks/test address only the original/default endpoint, never an arbitrary new endpoint. New endpoint management uses /api/platform-admin/integration-apps/{appId}/webhooks/endpoints (POST), .../endpoints/{endpointId} (GET/PUT/DELETE), and .../{endpointId}/rotate-secret or .../{endpointId}/test (POST). These are platform administration routes requiring an authenticated platform administrator, MFA and CSRF on writes, not customer OAuth access tokens. Publish the API and web app together and update all API instances before configuring additional endpoints.

Send test ping queues a signed ping with null organizationId, restaurantId and connectionId and no customer data. Queued does not mean delivered: confirm the result in delivery history. URLs must be publicly reachable HTTPS on port 443, without user credentials, query strings or fragments. Requests do not follow redirects and cannot target private addresses.

The integrating application's remaining work

The integrating application must implement its Connect button, callback/state verification, encrypted per-customer token storage, serialized refresh, disconnect, customer-organization mapping and signature-verifying webhook receiver. SmartShifts cannot change another application's code or register an unknown callback or receiver URL automatically. Polling remains available for initial sync and reconciliation.

Discovery: OAuth authorization-server metadata. Use this integration OAuth flow, not the separate MCP OAuth endpoints.