Smokeball User Management API Guide

Auth method: OAuth 2.0 (client credentials flow for server-to-server; authorization code flow for user-delegated access)

Setup steps

1. Register as a Smokeball API partner via the Smokeball developer program to obtain a client_id and client_secret.
2. Request an access token from the Smokeball OAuth 2.0 token endpoint using the appropriate grant type.
3. Include the Bearer token in the Authorization header of all API requests.
4. Tokens expire; implement refresh logic as documented in the API reference.

User object field mapping is not yet verified for this app.

Endpoint coverage is not yet verified for this app.

• Rate limits: No explicit rate-limit documentation found in publicly available Smokeball API docs.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Rate limit details are not publicly documented. Contact Smokeball partner support for specifics.

• Pagination method: none

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: No webhook or event-subscription documentation found in publicly available Smokeball API or help center docs.

• Alternative event strategy: Polling the Smokeball API for changes is the only documented approach based on available public documentation.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• No SCIM provisioning support documented for any Smokeball plan.
• SSO is available via Microsoft Entra ID integration but does not include automated user provisioning/deprovisioning via SCIM.
• User lifecycle management must be handled manually within the Smokeball application.

Three integration scenarios emerge from the available data, with hard constraints on each.

For matter/contact/document workflows, OAuth 2.0 client credentials can be used to retrieve a Bearer token and call documented legal-data endpoints - this is the intended API use case.

For staff onboarding, no API path exists;

the only supported method is manual creation in Settings > Staff, followed by role assignment in the UI, and if Entra SSO is configured

adding the user to the corresponding Entra group separately.

For staff offboarding, the same manual split applies: remove the user in Smokeball UI and revoke the Entra group membership independently.

Building an identity graph that includes Smokeball user state requires out-of-band data collection (e.g., admin-exported reports or support-assisted data pulls), since no user-object endpoints or SCIM feed are available to query programmatically.

Onboard a new staff member

1. Log in to the Smokeball application as a firm administrator.
2. Navigate to Settings > Staff and manually create the new user account.
3. Assign the appropriate role and permissions within the UI.
4. If SSO is configured via Microsoft Entra ID, ensure the user is added to the corresponding Entra group.

Watch out for: There is no API endpoint to automate staff creation. This must be done manually in the Smokeball UI.

Deprovision a departing staff member

1. Log in to the Smokeball application as a firm administrator.
2. Navigate to Settings > Staff and deactivate or remove the user.
3. If using Microsoft Entra SSO, remove the user from the Entra group to revoke SSO access.

Watch out for: No automated deprovisioning via SCIM or API is available; manual steps in both Smokeball and the IdP are required.

Integrate Smokeball matter data with a third-party system

1. Obtain API credentials through the Smokeball partner program.
2. Authenticate using OAuth 2.0 client credentials to retrieve a Bearer token.
3. Use documented Smokeball API endpoints (matters, contacts, documents) to read or write legal matter data.
4. Note: Staff/user management is out of scope for the API.

Watch out for: The Smokeball API covers legal practice data (matters, contacts, documents), not user administration. Do not expect user-management endpoints.

The core integration trap with Smokeball is assuming that Entra SSO coverage implies automated provisioning - it does not. SSO handles authentication only; there is no SCIM endpoint on any plan, so joiners and leavers are never propagated automatically.

A second trap is treating the Smokeball API as a user-management surface: it is explicitly a legal-data API, and any integration built on the assumption of staff-management endpoints will find no documented support.

For teams maintaining an identity graph across their SaaS stack via an MCP server with 60+ deep IT/identity integrations, Smokeball will appear as a gap - user state must be reconciled manually or via a compensating administrative process, not through a live API feed.