SugarCRM User Management API Guide

Auth method: OAuth 2.0 (password credentials grant or client credentials grant via SugarCRM's built-in OAuth 2.0 server)

Setup steps

1. In SugarCRM Admin, navigate to Admin > OAuth Keys and create an OAuth 2.0 consumer key and secret.
2. POST to /rest/v11_1/oauth2/token with grant_type=password, client_id, client_secret, username, and password to obtain an access_token and refresh_token.
3. Include the access_token in the OAuth-Token header on all subsequent API requests.
4. Use /rest/v11_1/oauth2/token with grant_type=refresh_token to refresh an expired access token.
5. For platform integrations, pass platform=base (or a custom platform key) in the token request to avoid session conflicts.

List Users

• Method: GET
• URL: /rest/v11_1/Users
• Watch out for: Deleted users (deleted=1) are excluded by default. Use show_deleted=1 query param to include them.

Request example

GET /rest/v11_1/Users?max_num=20&offset=0&fields=id,user_name,first_name,last_name,status
OAuth-Token: {access_token}

Response example

{
  "next_offset": 20,
  "records": [
    {"id":"abc-123","user_name":"jdoe","first_name":"John","last_name":"Doe","status":"Active"}
  ]
}

Get User by ID

• Method: GET
• URL: /rest/v11_1/Users/{id}
• Watch out for: Use /rest/v11_1/me to retrieve the currently authenticated user without knowing their ID.

Request example

GET /rest/v11_1/Users/abc-123?fields=id,user_name,email,status
OAuth-Token: {access_token}

Response example

{
  "id": "abc-123",
  "user_name": "jdoe",
  "status": "Active",
  "email": [{"email_address":"jdoe@example.com","primary_address":true}]
}

Create User

• Method: POST
• URL: /rest/v11_1/Users
• Watch out for: Password cannot be set via the REST API for SugarIdentity-managed cloud instances; user credentials are managed through SugarIdentity/IdP instead.

Request example

POST /rest/v11_1/Users
OAuth-Token: {access_token}
{
  "user_name": "jsmith",
  "last_name": "Smith",
  "first_name": "Jane",
  "status": "Active"
}

Response example

{
  "id": "def-456",
  "user_name": "jsmith",
  "first_name": "Jane",
  "last_name": "Smith",
  "status": "Active"
}

Update User

• Method: PUT
• URL: /rest/v11_1/Users/{id}
• Watch out for: Only an admin-level token can modify is_admin or status fields. Non-admin tokens can update their own record via /rest/v11_1/me.

Request example

PUT /rest/v11_1/Users/def-456
OAuth-Token: {access_token}
{
  "title": "Sales Manager",
  "department": "Sales"
}

Response example

{
  "id": "def-456",
  "title": "Sales Manager",
  "department": "Sales"
}

Deactivate / Soft-Delete User

• Method: DELETE
• URL: /rest/v11_1/Users/{id}
• Watch out for: This sets deleted=1 (soft delete). The user record is retained in the database. For SugarIdentity instances, deprovisioning should be done via SCIM or the IdP to fully revoke access.

Request example

DELETE /rest/v11_1/Users/def-456
OAuth-Token: {access_token}

Response example

{
  "id": "def-456"
}

Search / Filter Users

• Method: GET
• URL: /rest/v11_1/Users?filter[0][user_name]={value}
• Watch out for: Filter syntax uses bracket notation. Complex filters can also be sent via POST to /rest/v11_1/Users/filter with a JSON body.

Request example

GET /rest/v11_1/Users?filter[0][user_name]=jdoe&fields=id,user_name,status
OAuth-Token: {access_token}

Response example

{
  "next_offset": -1,
  "records": [
    {"id":"abc-123","user_name":"jdoe","status":"Active"}
  ]
}

Get Current Authenticated User

• Method: GET
• URL: /rest/v11_1/me
• Watch out for: Returns the user associated with the current OAuth token. Useful for verifying token identity without a known user ID.

Request example

GET /rest/v11_1/me
OAuth-Token: {access_token}

Response example

{
  "current_user": {
    "id": "abc-123",
    "user_name": "jdoe",
    "is_admin": false
  }
}

Revoke OAuth Token (Logout)

• Method: POST
• URL: /rest/v11_1/oauth2/logout
• Watch out for: Invalidates the current access token server-side. Should be called when deprovisioning integrations to prevent orphaned sessions.

Request example

POST /rest/v11_1/oauth2/logout
OAuth-Token: {access_token}

Response example

{
  "success": true
}

• Rate limits: SugarCRM does not publicly document specific rate limit thresholds in its REST API developer docs. Cloud instances may enforce limits at the infrastructure level; on-premise limits depend on server configuration.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official per-plan rate limit figures are published. Contact SugarCRM support for cloud instance limits.

• Pagination method: offset

• Default page size: 20

• Max page size: 1000

• Pagination pointer: offset and max_num

• Webhooks available: Yes

• Webhook notes: SugarCRM supports outbound webhooks via its 'Process Audit' and 'Sugar Process' (SugarBPM) module, as well as a dedicated Webhook module in Sugar 11+. Webhooks can be configured to fire on record create, update, or delete events for the Users module.

• Alternative event strategy: For real-time sync, SugarCRM also supports Logic Hooks (server-side PHP hooks) for on-premise deployments. Cloud instances use the Webhook module or SugarBPM triggers.

• Webhook events: after_save (User created or updated), after_delete (User soft-deleted)

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (requires SugarIdentity, available on Advanced and Premier cloud plans; SSO must be enabled as a prerequisite)

• Endpoint: https://id.sugarcrm.com/scim/v2 (SugarIdentity-managed endpoint; exact tenant URL provided during SugarIdentity setup)

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (deactivate user), GET /Groups (list groups/roles), GET /ServiceProviderConfig, GET /Schemas

Limitations:

• SCIM is only available on SugarIdentity-enabled cloud instances (not on-premise Sugar deployments).
• SSO must be configured as a prerequisite before SCIM provisioning can be enabled.
• SCIM endpoint URL is tenant-specific and provided by SugarCRM during SugarIdentity onboarding; it is not a generic public endpoint.
• Supported IdPs with documented SCIM connectors include Okta, Microsoft Entra ID (Azure AD), and OneLogin.
• Google Workspace SCIM provisioning is not officially documented as supported.
• Password sync is not supported via SCIM; authentication is handled by the IdP.

Three scenarios cover the majority of programmatic user lifecycle needs.

First, provisioning on non-SugarIdentity instances: POST to /rest/v11_1/Users with user_name, last_name, status=Active, and optional profile fields;

store the returned GUID;

assign roles via /rest/v11_1/Users/{id}/link/roles.

Note that password cannot be set via the REST API even on non-SugarIdentity instances - it must be handled through the Admin UI or a direct database operation.

Second, deprovisioning on SugarIdentity/Enterprise cloud: always initiate from the IdP side (Okta, Entra ID, or OneLogin);

the IdP sends a SCIM PATCH or DELETE to the SugarIdentity endpoint, which propagates status=Inactive to the CRM.

Calling DELETE /rest/v11_1/Users/{id} directly sets deleted=1 but does not revoke the user's IdP session or SugarIdentity credentials.

Third, bulk audit: paginate GET /rest/v11_1/Users using offset and max_num (cap at 1000);

iterate until next_offset returns -1;

filter by status=Active and sort by date_modified to surface stale accounts.

Provision a new user via REST API (non-SugarIdentity instance)

1. POST to /rest/v11_1/oauth2/token with admin credentials to obtain an admin access_token.
2. POST to /rest/v11_1/Users with required fields: user_name, last_name, status=Active, and optionally email, title, department.
3. Store the returned id (GUID) for future update or deactivation operations.
4. Optionally assign roles by POSTing to /rest/v11_1/Users/{id}/link/roles with the role record ID.

Watch out for: Password must be set separately via the Sugar admin UI or a direct database operation on non-SugarIdentity instances; the REST API does not expose a password field for security reasons.

Deprovision a user via SCIM (SugarIdentity / Enterprise cloud)

1. Ensure SugarIdentity is enabled and SCIM is configured in your IdP (Okta, Entra ID, or OneLogin).
2. In the IdP, unassign the SugarCRM application from the user or deactivate the user in the IdP directory.
3. The IdP sends a SCIM PATCH or DELETE request to the SugarIdentity SCIM endpoint to set the user's active attribute to false.
4. SugarIdentity propagates the deactivation to the SugarCRM instance, setting user status to Inactive and revoking SSO access.
5. Verify deactivation by calling GET /rest/v11_1/Users/{id} and confirming status=Inactive.

Watch out for: Deprovisioning via the SugarCRM REST API alone (DELETE /Users/{id}) does not revoke the user's IdP session or SugarIdentity credentials. Always deprovision from the IdP side when SugarIdentity is in use.

Bulk-read and audit all active users

1. Authenticate via POST /rest/v11_1/oauth2/token to get an admin access_token.
2. GET /rest/v11_1/Users?fields=id,user_name,first_name,last_name,status,email,date_modified&max_num=100&offset=0&filter[0][status]=Active
3. Check the next_offset value in the response; if next_offset != -1, repeat the request incrementing offset by max_num until next_offset returns -1.
4. Aggregate all records across pages for the full active user list.

Watch out for: Setting max_num above 1000 is not supported and may be silently capped. For very large instances, paginate carefully and avoid parallel requests that could trigger infrastructure-level throttling.

Several non-obvious constraints create integration risk. Bulk/batch operations are not natively supported - mass updates require individual PUT/PATCH calls per record, which is a throughput concern on large instances. OAuth tokens expire after 3600 seconds;

refresh tokens are also finite, so integrations must handle proactive refresh or face silent auth failures. The platform parameter in the token request matters: reusing platform=base on a cloud instance can conflict with active user sessions - use a unique custom platform key for integrations. Soft deletes (deleted=1) do not immediately terminate active sessions;

on SugarIdentity instances, only IdP-side deprovisioning fully revokes access. Rate limits are not publicly documented for cloud instances and must be confirmed with SugarCRM support, making capacity planning for high-volume sync jobs speculative.

Finally, custom fields added via Studio are accessible via the API but must be explicitly requested using the fields parameter - they are not returned by default, which can cause silent data gaps in identity graph pipelines that rely on enriched user attributes.