Automox User Management API Guide

Auth method: API Key (Bearer token passed as Authorization header or api_key query parameter)

Setup steps

1. Log in to the Automox Console.
2. Navigate to Settings > API Keys.
3. Click 'Generate API Key', provide a name, and save.
4. Copy the generated key; it is shown only once.
5. Pass the key as a Bearer token: Authorization: Bearer <api_key>, or as a query parameter ?api_key=<api_key>.

Required scopes

List Users

• Method: GET
• URL: https://console.automox.com/api/users?o={org_id}
• Watch out for: The o (organization ID) query parameter is required. Omitting it returns a 400 error.

Request example

GET /api/users?o=12345&limit=25&page=0
Authorization: Bearer <api_key>

Response example

[
  {
    "id": 101,
    "email": "alice@example.com",
    "firstname": "Alice",
    "lastname": "Smith",
    "role": "admin",
    "status": "active"
  }
]

Get User

• Method: GET
• URL: https://console.automox.com/api/users/{id}?o={org_id}
• Watch out for: Returns 404 if the user ID does not belong to the specified organization.

Request example

GET /api/users/101?o=12345
Authorization: Bearer <api_key>

Response example

{
  "id": 101,
  "email": "alice@example.com",
  "firstname": "Alice",
  "lastname": "Smith",
  "role": "admin",
  "status": "active"
}

Create User (Invite)

• Method: POST
• URL: https://console.automox.com/api/users?o={org_id}
• Watch out for: Creates an invitation; user status is pending until the invite is accepted. Duplicate email returns 409.

Request example

POST /api/users?o=12345
Content-Type: application/json
{
  "email": "bob@example.com",
  "firstname": "Bob",
  "lastname": "Jones",
  "role": "operator"
}

Response example

{
  "id": 202,
  "email": "bob@example.com",
  "status": "pending"
}

Update User

• Method: PUT
• URL: https://console.automox.com/api/users/{id}?o={org_id}
• Watch out for: Uses PUT (full replacement semantics for mutable fields). Read-only fields like id and status are ignored.

Request example

PUT /api/users/202?o=12345
Content-Type: application/json
{
  "firstname": "Robert",
  "role": "admin"
}

Response example

{
  "id": 202,
  "email": "bob@example.com",
  "firstname": "Robert",
  "role": "admin"
}

Delete User

• Method: DELETE
• URL: https://console.automox.com/api/users/{id}?o={org_id}
• Watch out for: Deletes the user from the organization. Cannot delete the last admin user of an org.

Request example

DELETE /api/users/202?o=12345
Authorization: Bearer <api_key>

Response example

HTTP 204 No Content

Get Self (Current API Key User)

• Method: GET
• URL: https://console.automox.com/api/users/self
• Watch out for: Returns the user associated with the API key in use; useful for validating key identity.

Request example

GET /api/users/self
Authorization: Bearer <api_key>

Response example

{
  "id": 101,
  "email": "alice@example.com",
  "role": "admin"
}

List Organizations

• Method: GET
• URL: https://console.automox.com/api/orgs
• Watch out for: Required to obtain the org_id used in all user-management calls. Multi-org accounts return multiple entries.

Request example

GET /api/orgs
Authorization: Bearer <api_key>

Response example

[
  {
    "id": 12345,
    "name": "Acme Corp",
    "plan": "business"
  }
]

• Rate limits: Automox enforces rate limits on API requests. The official docs note a limit of 2,500 requests per 5-minute window per API key.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: When the limit is exceeded the API returns HTTP 429. Official docs do not explicitly document rate-limit response headers or a Retry-After header.
• Pagination method: offset
• Default page size: 25
• Max page size: 500
• Pagination pointer: limit / page

• Webhooks available: No
• Webhook notes: Automox does not offer native outbound webhooks for user-management events as of the current documentation.
• Alternative event strategy: Poll the GET /users endpoint on a schedule to detect user changes, or use SCIM provisioning events via your IdP.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Not explicitly gated by plan in official docs; SSO is not listed as a prerequisite.

• Endpoint: https://console.automox.com/api/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 attributes, including active status for deprovisioning), DELETE /Users/{id} (delete user)

Limitations:

• SCIM Groups provisioning support is not documented in the official help article; only User provisioning is confirmed.
• The SCIM endpoint URL and bearer token are generated within the Automox Console under Settings > SCIM; the token is shown only once.
• IdP-specific connector configuration (e.g., Okta SCIM app) is required on the IdP side; Automox does not publish IdP-specific setup guides beyond the generic SCIM article.

Three scenarios cover the primary automation surface.

First, provisioning: GET /api/orgs to resolve org_id, then POST /api/users?o={org_id} with email, name, and role

the user lands in pending status until invite acceptance, and polling GET /api/users/{id} is the only way to detect activation since no webhook exists for this event.

Second, soft deprovisioning via SCIM: PATCH /api/scim/v2/Users/{id} with active: false disables the account without permanent deletion;

DELETE via SCIM or REST is immediate and irreversible, and the last admin in an org cannot be deleted.

Third, bulk user enumeration: paginate GET /api/users?o={org_id}&limit=500&page=0, incrementing page until the response array length falls below the limit value - with large orgs, monitor cumulative request count against the 2,500/5-min rate cap.

The SCIM bearer token is a separate credential from the REST API key and must be regenerated in the Console if lost.

Provision a new user and confirm activation

1. GET /api/orgs to retrieve the target org_id.
2. POST /api/users?o={org_id} with email, firstname, lastname, and role to send an invitation.
3. Store the returned user id.
4. Poll GET /api/users/{id}?o={org_id} until status changes from pending to active (user has accepted the invite).

Watch out for: There is no webhook to signal invite acceptance; polling is the only mechanism via the REST API.

Deprovision a user via SCIM (soft disable)

1. Obtain the SCIM bearer token from Automox Console > Settings > SCIM.
2. GET /api/scim/v2/Users?filter=userName eq "user@example.com" to find the SCIM user ID.
3. PATCH /api/scim/v2/Users/{id} with body {"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"replace","path":"active","value":false}]} to disable without deleting.

Watch out for: Using DELETE via SCIM permanently removes the user. Use PATCH active=false for reversible deprovisioning.

Bulk-list all users across a paginated org

1. GET /api/users?o={org_id}&limit=500&page=0
2. Check if the response array length equals limit; if so, increment page and repeat.
3. Continue until a response returns fewer items than limit, indicating the last page.

Watch out for: Max page size is 500. With large user counts, multiple requests are needed. Monitor request count against the 2,500/5-min rate limit.

The most common integration pitfall is treating user creation as synchronous activation. POST /api/users sends an invitation email; the user object is pending until the invite is accepted, so any downstream logic that assumes an active account immediately after creation will produce false positives in identity graph state.

A second trap is key-permission inheritance: automations built on a key generated by an Operator-role user will silently fail on admin-scoped endpoints - always generate keys from an Administrator account for full operational coverage. Finally, SCIM Groups provisioning is not confirmed in official documentation;

only User-level SCIM operations are supported, so role assignment via SCIM group push may not behave as expected and should be validated before relying on it in production identity graph sync workflows.