Register a computer
POST/computers/register
Registers a Windows, Linux or macOS computer, or re-registers one that is already in inventory.
For Windows and Linux the call queues a registration scan and waits up to 90 seconds for it to finish, then applies the requested policy and persistent administrators.
Required role:
- A token with role
superadminoradmin. - An access token from an API key with scope
system:registeris accepted on this route (scoped tokens are refused elsewhere), but its linked user must still besuperadminoradminunless the next rule applies. - When the
unauthenticated_registration_endpointsfeature is enabled, any caller is allowed, including a plainuseror no token.
Otherwise the call returns 403.
Per operating system
| Field | Windows | Linux | macOS |
|---|---|---|---|
system | FQDN of a computer already in inventory (found by directory sync) | FQDN; created if new | FQDN; created if new |
username, password | required | required, unless the caller is an admin and a domain service account is configured for Linux (and not nondomain) | same rule, using the macOS configuration |
secure | allowed | allowed | rejected (422) |
| registration scan | always | always | only when scanNow or secure is true; otherwise the call returns 201 with the new id |
If a Windows computer is already registered, persistent, scan and secure are ignored. For Linux and macOS, only an admin can change the OS type, nondomain or directory_bridging of a computer that already exists.
The body can be JSON or urlencoded. Booleans accept true or false as strings.
Request
Responses
- 200
- 201
- 401
- 403
- 408
- 422
Registration scan completed. The body is the last queue activity entry.
macOS only. Registered without a scan. The body is the new computer's id as a JSON string.
A token was sent but is invalid or expired (for example jwt malformed). A request with no token is not a 401 on this route: it returns 403 unless unauthenticated_registration_endpoints is enabled.
The token's role is not allowed for this operation, or the token's scopes exclude the route
(Scope not allowed by token).
The registration scan did not complete within 90 seconds. Body is {name: "TimeoutError", message: "Operation timed out"}.
Missing system ("No system specified."); invalid os_type ("Invalid os_type. Must be one of linux, macos, windows"); missing credentials for a Windows computer ("Must provide username and password for registration."); the request cannot be processed for the supplied computer; unknown domain for Linux (Unknown domain specified: "<domain>"); a non-admin trying to change OS type, nondomain or bridging; protect mode on macOS ("Protect mode registration not yet supported for MacOS"); or the registration scan failed (message is then the worker activity message and code its activity code).