Using Global API Keys
We have added Global API Keys, which allow customers to use our APIs across all organizations under their account, rather than for a single organization. Note that some API endpoints will continue to accept a regular organization API key, assuming that endpoint is only checking permissions at the account and/or global scopes.
Important
Keep API Keys Secure!
Depending on your role, your API key may be able to modify users, devices, and policies. API keys should be kept secure and not shared to prevent unforeseen changes or potential security issues. Never email or write down your API key.
API Keys Overview
Automox supports two types of API keys: Organization API Keys and Global API Keys.
Organization API Keys
- Created within a specific organization.
- Can only be used when making requests to that same organization.
- The access granted matches the permissions of the user who created the key within that organization.
Note
Some API endpoints will continue to accept a regular organization API key, assuming that endpoint is only checking permissions at the account and/or global scopes.
Global API Keys
- Valid across all organizations within your Automox account.
- When used, they inherit the permissions that the key owner has in the organization being targeted by the request.
- This means your access level will depend on your assigned permissions in whichever organization the API call is directed to.
Quick Example
- If you create an Organization API Key in Org A, you can always use it for API calls targeting Org A, but not necessarily for API calls targeting Org B.
- If you create a Global API Key, you can use it to make API calls against Org A, Org B, or any other org in your account. The permissions applied in each case will match your role in the org you are targeting.
Permissions and Scopes
We have various permissions that have scopes associated with them. Some permissions are can only be attached at a specific scope, whereas other permissions can attached at any combination of account, global, organization scopes. Additionally, some permissions have conditions that must be met in order to use the API. We have added information about the required permissions to our API endpoints. See the following table for a listing of permissions and scopes.
| Endpoint | Required Permission | Scope | Conditions | Documentation Notes |
|---|---|---|---|---|
| GET /servers/{id}/queues | devices:read | Organization | View upcoming commands for a specific device | |
| POST /servers/{id}/queues | devices:manage | Organization | Force immediate scan/patch/reboot on a device | |
| GET /servers | devices:read | Organization | List all devices in organization | |
| GET /servers/{id} | devices:read | Organization | View specific device details | |
| PUT /servers/{id} | devices:manage | Organization | Update device configuration | |
| DELETE /servers/{id} | devices:delete | Organization | Remove device from organization | |
| POST /servers/batch | devices:manage | Organization | Update multiple devices in batch | |
| GET /device-details/orgs/{org_UUID}/devices/{device_UUID}/inventory | devices:read | Organization | View device software inventory | |
| GET /device-details/orgs/{org_UUID}/devices/{device_UUID}/categories | devices:read | Organization | View device software categories | |
| GET /servers/{id}/packages | package:read | Organization | View software packages for specific device | |
| GET /orgs/{id}/packages | package:read | Organization | List all packages for organization | |
| GET /worklet-catalog | custom_policy:read | Organization | View worklet catalog (deprecated feature) | |
| GET /worklet-catalog/{uuid-legacy_id} | custom_policy:read | Organization | View specific worklet (deprecated feature) | |
| GET /servergroups | server_group:read | Organization | List all server groups | |
| POST /servergroups | server_group:create | Organization | Create new server group | |
| GET /servergroups/{id} | server_group:read | Organization | User must be affiliated with the group | View specific server group |
| PUT /servergroups/{id} | server_group:modify | Organization | User must be affiliated with the group | Update server group |
| DELETE /servergroups/{id} | server_group:delete | Organization | User must be affiliated with the group | Delete server group |
| GET /approvals | approval:read | Organization | List manual approval requests | |
| PUT /approvals/{id} | approval:update | Organization | Update manual approval status | |
| GET /events | organization:read | Organization | View organization event logs | |
| GET /data-extracts | report:read | Organization | List data export jobs | |
| POST /data-extracts | report:read | Organization | Create new data export job | |
| GET /data-extracts/{id} | report:read | Organization | View specific data export job | |
| GET /data-extracts/{id}/download | report:read | Organization | Download completed data export | |
| GET /orgs | organization:read | Account OR Global OR Organization | List the organizations in the account that the authenticated user has access to. Note: if a user doesn't have "devices:add" org-scoped permission, the corresponding org data is still returned, but no access key attached. Also, any orgs that the user doesn't have org:read permission in in rbac-cr are filtered out. | |
| GET /policies | Multiple policy types:read | Organization | Requires read permission for patch_policy, required_software_policy, and/or custom_policy depending on policy types | |
| POST /policies | Multiple policy types:create | Organization | Requires create permission for the specific policy type being created | |
| GET /policies/{id} | Multiple policy types:read | Organization | Requires read permission for the specific policy type | |
| PUT /policies/{id} | Multiple policy types:modify | Organization | Requires modify permission for the specific policy type | |
| DELETE /policies/{id} | Multiple policy types:delete | Organization | Requires delete permission for the specific policy type | |
| POST /policies/{id}/files | Multiple policy types:modify | Organization | Upload files to policies | |
| POST /policies/{id}/action | Multiple policy types:execute | Organization | Execute policy immediately | |
| POST /policies/device-filters-preview | devices:read | Organization | Preview devices matching filter criteria | |
| GET /policystats | report:read | Organization | View policy compliance statistics | |
| GET /orgs/{id}/api_keys | all_api_keys:list | Organization | List all API keys for organization | |
| GET /users/{userId}/api_keys/{id} | all_api_keys:read OR user_api_key:manage | Organization | all_api_keys:read for admin access, user_api_key:manage for own keys | View API key details |
| PUT /users/{userId}/api_keys/{id} | all_api_keys:modify OR user_api_key:manage | Organization | all_api_keys:modify for admin access, user_api_key:manage for own keys | Enable/disable API key |
| POST /users/{userId}/api_keys/{id}/decrypt | user_api_key:manage | Organization | User must own the API key | Decrypt API key value |
| GET /users | users:read | Account OR Global | List users | |
| POST /users | None | None | No authentication required | Public user registration |
| GET /users/{id} | users:read | Account OR Global | No permission required if viewing own user data | View user details |
| PUT /users/{userId} | users:modify OR None | Organization OR None | users:modify for admin updates, no permission required for self-updates | Update user (full replacement) |
| PATCH /users/{userId} | users:modify OR None | Organization OR None | users:modify for admin updates, no permission required for self-updates | Update user (partial update) |
| DELETE /users/{id} | users:delete | Organization | Cannot delete own account | Delete user |
| GET /users/self | None | None | Authentication required only | View own user profile |
| GET /accounts/{accountId}/rbac-roles | role:read | Global | List available RBAC roles | |
| GET /accounts/{accountId} | account:read | Account | View account information | |
| GET /accounts/{accountId}/users/{userId} | users:read | Account OR Global | No permission required if viewing own data | View account user details |
| DELETE /accounts/{accountId}/users/{userId} | users:delete | Required at every scope where user has role assignments | Remove user from account | |
| POST /accounts/{accountId}/invitations | users:invite | Required at every scope where role assignments will be made | Invite user to account with zone access | |
| GET /accounts/{accountId}/users/{userId}/zones | organization:read | Account OR Global | List zones user has access to | |
| POST /accounts/{accountId}/zones | organization:create | Account | Create new zone | |
| GET /accounts/{accountId}/zones | organization:read | Account OR Global | List account zones | |
| GET /accounts/{accountId}/zones/{zoneId} | organization:read | Organization | View specific zone details | |
| GET /accounts/{accountId}/zones/{zoneId}/users | users:read | Organization | List users in zone | |
| GET /orgs/{orgID}/remediations/action-sets/upload/formats | remediation:read | Organization | List supported CSV upload formats | |
| POST /orgs/{orgID}/remediations/action-sets/upload | remediation:create | Organization | Upload vulnerability remediation CSV | |
| GET /orgs/{orgID}/remediations/action-sets/{actionSetID} | remediation:read | Organization | View specific action set | |
| DELETE /orgs/{orgID}/remediations/action-sets/{actionSetID} | remediation:delete | Organization | Delete action set | |
| GET /orgs/{orgID}/remediations/action-sets/{actionSetID}/solutions | remediation:read | Organization | List solutions in action set | |
| GET /orgs/{orgID}/remediations/action-sets/{actionSetID}/issues | remediation:read | Organization | List issues found during import | |
| GET /orgs/{orgID}/remediations/action-sets | remediation:read | Organization | List all action sets | |
| DELETE /orgs/{orgID}/remediations/action-sets | remediation:delete | Organization | Bulk delete action sets | |
| POST /orgs/{orgID}/remediations/action-sets/{actionSetID}/actions | remediation:execute | Organization | Execute remediation actions | |
| GET /reports/prepatch | report:read | Organization | When using groupId parameter, user must have report:read permission on the group's organization | View pre-patch report |
| GET /reports/needs-attention | report:read | Organization | View devices needing attention report | |
| POST /policies/{policyID}/clone | Source policy read permission + target policy create permission | Multiple Organizations | Requires read permission on source policy type and create permission for same policy type in all target organizations | Clone policy to multiple organizations |
| DELETE /users/{userId}/api_keys/{id} | all_api_keys:delete OR user_api_key:manage | Organization | all_api_keys:delete for admin access, user_api_key:manage for own keys | Delete API key |
| GET /wis/search | None (only need to be authenticated) | N/A | Search worklets by query | |
| GET /wis/search/{id} | None (only need to be authenticated) | N/A | Load a worklet by UUID/Legacy id/Alias | |
| POST /config/consent/account/{accountUUID}/org/{orgUUID}/device | remote_control_consent:manage | Organization | Exclude/include a device from remote consent | |
| DELETE /global/api_keys/{key_id} | user_api_key:manage OR all_api_keys:delete | Account OR Global | If the user only has the user_api_key:manage permission, the user must own the key in order to delete it. | |
| GET /global/api_keys | user_api_key:manage OR all_api_keys:list | Account OR Global | If a user only has the user_api_key:manage permission, only the keys they own will be returned. | |
| POST /global/api_keys | user_api_key:manage | Account OR Global | ||
| POST /global/api_keys/{key_id}/decrypt | user_api_key:manage | Account OR Global | The user must own the key in order to decrypt it. | |
| PUT /global/api_keys/{key_id} | user_api_key:manage OR all_api_keys:modify | Account OR Global | If the user only has the user_api_key:manage permission, the user must own the key in order to delete it. |