Mixpanel User Management API Guide

Auth method: Service Account credentials (Basic Auth with username:secret) or Project Secret (Basic Auth). SCIM uses a dedicated SCIM OAuth token.

Setup steps

1. Navigate to Organization Settings > Service Accounts and create a Service Account with appropriate role.
2. Copy the Service Account username and secret.
3. Encode credentials as Base64(username:secret) and pass in the Authorization header as 'Basic '.
4. For project-level Engage/Ingestion API, use the Project Secret found under Project Settings > Access Keys.
5. For SCIM provisioning, generate a SCIM token in Organization Settings > Security > SCIM and use it as a Bearer token.

Required scopes

Set / Create User Profile

• Method: POST
• URL: https://api.mixpanel.com/engage#profile-set
• Watch out for: Uses $set operation; properties not included are left unchanged. Use $set_once to avoid overwriting existing values.

Request example

POST /engage
Content-Type: application/json

{"$token":"PROJECT_TOKEN","$distinct_id":"user_123","$set":{"$email":"user@example.com","$name":"Jane Doe","plan":"pro"}}

Response example

{"status": 1, "error": null}

Update User Profile (Append/Increment)

• Method: POST
• URL: https://api.mixpanel.com/engage#profile-numerical-add
• Watch out for: $add only works on numeric properties. Use $append for list properties.

Request example

POST /engage

{"$token":"PROJECT_TOKEN","$distinct_id":"user_123","$add":{"login_count":1}}

Response example

{"status": 1, "error": null}

Delete User Profile

• Method: POST
• URL: https://api.mixpanel.com/engage#profile-delete
• Watch out for: Deletes the profile but does NOT delete associated event data. GDPR deletion requires a separate deletion API call.

Request example

POST /engage

{"$token":"PROJECT_TOKEN","$distinct_id":"user_123","$delete":""}

Response example

{"status": 1, "error": null}

Batch Ingest User Profiles

• Method: POST
• URL: https://api.mixpanel.com/engage
• Watch out for: Max 2,000 records per batch request. Prefer /import endpoint for large-scale ingestion.

Request example

POST /engage

[{"$token":"TOKEN","$distinct_id":"u1","$set":{"$email":"a@b.com"}},{"$token":"TOKEN","$distinct_id":"u2","$set":{"$email":"c@d.com"}}]

Response example

{"status": 1, "error": null}

Query User Profiles (Engage Query)

• Method: POST
• URL: https://mixpanel.com/api/2.0/engage
• Watch out for: Uses a different base URL (mixpanel.com not api.mixpanel.com). Requires Project Secret auth. Paginate using session_id + incrementing page param.

Request example

POST /api/2.0/engage
Authorization: Basic <base64(secret:)>

{"where":"properties[\"$email\"] == \"user@example.com\"","page_size":100}

Response example

{"status":"ok","results":[{"$distinct_id":"user_123","$properties":{"$email":"user@example.com"}}],"session_id":"abc123","page":0,"total":1}

GDPR Delete User Data

• Method: POST
• URL: https://mixpanel.com/api/app/data-deletions/v3.0/
• Watch out for: Deletion is asynchronous; poll the task status endpoint. Deletes both events and profiles. Irreversible.

Request example

POST /api/app/data-deletions/v3.0/
Authorization: Basic <base64(secret:)>

{"distinct_ids":["user_123"],"compliance_type":"GDPR"}

Response example

{"status":"ok","results":{"task_id":"del_abc123"}}

SCIM List Users

• Method: GET
• URL: https://mixpanel.com/api/app/scim/v2/Users
• Watch out for: SCIM token is separate from Service Account credentials. Enterprise plan + SSO required.

Request example

GET /api/app/scim/v2/Users?startIndex=1&count=100
Authorization: Bearer <SCIM_TOKEN>

Response example

{"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults":2,"Resources":[{"id":"u1","userName":"user@example.com","active":true}]}

SCIM Create / Provision User

• Method: POST
• URL: https://mixpanel.com/api/app/scim/v2/Users
• Watch out for: Provisioned users receive an email invitation. Role assignment via SCIM is limited; use IDP group mappings for role control.

Request example

POST /api/app/scim/v2/Users
Authorization: Bearer <SCIM_TOKEN>

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"new@example.com","name":{"givenName":"New","familyName":"User"},"active":true}

Response example

{"id":"u_new","userName":"new@example.com","active":true,"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"]}

• Rate limits: Mixpanel enforces rate limits per project and per endpoint family. Ingestion (track/engage) limits differ from query API limits.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when limits are exceeded. Retry-After header indicates wait time. Batch ingestion via /import is preferred for bulk operations to reduce request overhead.
• Pagination method: cursor
• Default page size: 1000
• Max page size: 1000
• Pagination pointer: session_id + page (Engage query API uses session_id returned in first response, then page=0,1,2...)

• Webhooks available: No
• Webhook notes: Mixpanel does not offer native outbound webhooks for user-management or profile events.
• Alternative event strategy: Use Mixpanel's Cohort Sync or Data Pipelines (Enterprise) to export user data to external systems. For real-time triggers, poll the Engage Query API or use a CDP integration.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://mixpanel.com/api/app/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create/provision user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user, including deactivate via active=false), DELETE /Users/{id} (deprovision user), GET /Groups (list groups), POST /Groups (create group), PATCH /Groups/{id} (update group membership), DELETE /Groups/{id} (delete group)

Limitations:

• Requires SSO to be configured before SCIM can be enabled.
• Enterprise plan required; not available on Free or Growth.
• SCIM token is a single org-level token; rotation requires manual regeneration in UI.
• Role assignment granularity via SCIM is limited; project-level roles must be managed separately or via IDP group-to-role mappings.
• Deprovisioning sets user to inactive but may not immediately revoke active sessions without SSO enforcement.
• Supported IdPs with documented integration: Okta, Microsoft Entra ID (Azure AD), OneLogin.

Three integration patterns cover the majority of programmatic use cases:

• Bulk CRM profile import: Transform CRM records into Engage payloads keyed on $distinct_id, chunk into batches of ≤2,000, and POST to https://api.mixpanel.com/engage. For volumes in the millions, use the /import endpoint instead - it is optimized for throughput and avoids the silent record-drop behavior that occurs when the 2,000-record batch limit is exceeded.

• SCIM + Okta provisioning/deprovisioning: Requires Enterprise plan and a fully configured SAML SSO setup before the SCIM token can be generated. Okta sends POST /Users to provision and PATCH /Users/{id} with active=false to deprovision. Project-level role assignments are not controlled via SCIM; assign them manually post-provisioning or via Okta group-to-role mappings where supported.

• GDPR right-to-erasure: Identify the user's $distinct_id via the Engage Query API, submit a deletion task to POST /api/app/data-deletions/v3.0/, and poll the task status until COMPLETE. The $delete Engage operation removes the profile record immediately, but event data deletion is asynchronous and can take days - do not confirm erasure until the task status is verified.

Bulk-import user profiles from a CRM

1. Obtain the Project Token from Project Settings > Access Keys.
2. Transform CRM records into Mixpanel Engage payload format with $distinct_id, $email, $name, and custom properties.
3. Chunk records into batches of ≤2,000 and POST each batch to https://api.mixpanel.com/engage as a JSON array.
4. Check response for {"status":1} per batch; log and retry any failed batches with exponential backoff.
5. Verify profiles appear in Mixpanel UI under Users > Explore.

Watch out for: Use the /import endpoint for very large volumes (millions of records) as it is optimized for bulk ingestion and has higher throughput limits than /engage.

Provision and deprovision employees via SCIM + Okta

1. Confirm Enterprise plan is active and SSO (SAML) is configured in Mixpanel Organization Settings.
2. Generate a SCIM token in Organization Settings > Security > SCIM Provisioning.
3. In Okta, add the Mixpanel SCIM app, set Base URL to https://mixpanel.com/api/app/scim/v2, and paste the SCIM token as the API token.
4. Enable provisioning features: Push New Users, Push Profile Updates, Deactivate Users.
5. Assign Okta users/groups to the Mixpanel app; Okta will POST /Users to provision them.
6. When an employee is offboarded in Okta, Okta sends PATCH /Users/{id} with active=false, deprovisioning the Mixpanel account.

Watch out for: Project-level role assignments are not fully controlled via SCIM; use Okta group-to-Mixpanel-role mappings where supported, or assign roles manually after provisioning.

GDPR right-to-erasure: delete all data for a user

1. Identify the user's $distinct_id(s) - query via POST /api/2.0/engage with a where clause filtering by $email.
2. POST to https://mixpanel.com/api/app/data-deletions/v3.0/ with {"distinct_ids":[""],"compliance_type":"GDPR"} using Project Secret Basic Auth.
3. Record the returned task_id.
4. Poll GET /api/app/data-deletions/v3.0/?task_id= until status is 'COMPLETE'.
5. Also POST to /engage with $delete operation to remove the user profile immediately (event deletion is async via the deletion task).

Watch out for: The $delete Engage operation removes the profile record but event data persists until the async deletion task completes (can take days). Do not confirm erasure to the user until the task status is COMPLETE.

The most common integration trap is conflating the two Engage endpoints. The ingestion endpoint (POST https://api.mixpanel.com/engage) authenticates with the Project Token and writes profiles. The query endpoint (POST https://mixpanel.com/api/2.0/engage) authenticates with the Project Secret and reads profiles.

Using the wrong credential on either endpoint returns an auth error that does not clearly indicate the URL mismatch as the root cause.

A second trap is profile deletion scope. Calling $delete on the Engage ingestion endpoint removes the user profile record but leaves all associated event data intact. GDPR-compliant full erasure requires a separate, asynchronous call to the Data Deletion API - a two-step process that is easy to implement incompletely.

For teams using SCIM: the SCIM token is a single org-level credential with no scoped permissions and no automatic rotation. Rotation requires manual regeneration in the UI, which immediately invalidates the existing token and breaks any active IDP sync until the new token is updated.

Plan token rotation as a coordinated change, not a background task.