Fleet User Management API Guide

Auth method: API token (Bearer token) passed in Authorization header; tokens are generated per user via the Fleet UI or login endpoint

Setup steps

1. POST to /api/v1/fleet/login with email and password to receive a token.
2. Alternatively, generate an API-only user token via Fleet UI under Account Settings > API token.
3. Include the token in all requests as: Authorization: Bearer
4. For SSO-enabled instances, API-only users must be created separately as SSO users cannot generate API tokens.

Required scopes

Login / obtain API token

• Method: POST
• URL: /api/v1/fleet/login
• Watch out for: SSO-enabled users cannot use this endpoint; they must authenticate via the SSO flow. Use api_only users for token-based automation.

Request example

POST /api/v1/fleet/login
{
  "email": "admin@example.com",
  "password": "supersecret"
}

Response example

{
  "user": {"id": 1, "name": "Admin", "email": "admin@example.com"},
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

List users

• Method: GET
• URL: /api/v1/fleet/users
• Watch out for: Requires Admin role. Returns all users globally; team-scoped filtering is not available on this endpoint.

Request example

GET /api/v1/fleet/users?page=0&per_page=50
Authorization: Bearer <token>

Response example

{
  "users": [
    {"id": 1, "name": "Admin", "email": "admin@example.com",
     "global_role": "admin", "api_only": false}
  ]
}

Create user

• Method: POST
• URL: /api/v1/fleet/users/admin
• Watch out for: This endpoint creates users without sending an invitation email. To invite via email, use POST /api/v1/fleet/invites instead.

Request example

POST /api/v1/fleet/users/admin
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "Str0ngPass!",
  "global_role": "observer"
}

Response example

{
  "user": {
    "id": 42,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "global_role": "observer"
  }
}

Get user by ID

• Method: GET
• URL: /api/v1/fleet/users/{id}
• Watch out for: Users can retrieve their own record; retrieving other users requires Admin role.

Request example

GET /api/v1/fleet/users/42
Authorization: Bearer <token>

Response example

{
  "user": {
    "id": 42,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "global_role": "observer"
  }
}

Update user

• Method: PATCH
• URL: /api/v1/fleet/users/{id}
• Watch out for: Setting global_role will clear all team-level roles, and vice versa. They are mutually exclusive.

Request example

PATCH /api/v1/fleet/users/42
{
  "global_role": "maintainer",
  "name": "Jane Smith"
}

Response example

{
  "user": {
    "id": 42,
    "name": "Jane Smith",
    "global_role": "maintainer"
  }
}

Delete user

• Method: DELETE
• URL: /api/v1/fleet/users/{id}
• Watch out for: Requires Admin role. Deletion is immediate and irreversible; no soft-delete or deactivation state exists.

Request example

DELETE /api/v1/fleet/users/42
Authorization: Bearer <token>

Response example

{}

Invite user (email invitation)

• Method: POST
• URL: /api/v1/fleet/invites
• Watch out for: Requires SMTP to be configured on the Fleet server. Invites expire; check invite status via GET /api/v1/fleet/invites.

Request example

POST /api/v1/fleet/invites
{
  "email": "newuser@example.com",
  "name": "New User",
  "global_role": "observer"
}

Response example

{
  "invite": {
    "id": 7,
    "email": "newuser@example.com",
    "global_role": "observer"
  }
}

Logout / invalidate token

• Method: POST
• URL: /api/v1/fleet/logout
• Watch out for: Invalidates only the token used in the request. Other active tokens for the same user remain valid.

Request example

POST /api/v1/fleet/logout
Authorization: Bearer <token>

Response example

{}

• Rate limits: Fleet does not document explicit rate limits in its official REST API docs. Rate limiting is not enforced by default in the open-source version; self-hosted operators may configure upstream proxies.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate limit documentation found. Fleet is self-hosted; limits depend on operator infrastructure.

• Pagination method: offset

• Default page size: 20

• Max page size: 0

• Pagination pointer: page and per_page (e.g., ?page=0&per_page=100)

• Webhooks available: No

• Webhook notes: Fleet does not offer user lifecycle webhooks (e.g., user.created, user.deleted). Fleet does support webhooks for host/vulnerability/policy events, but not for user management events.

• Alternative event strategy: Poll GET /api/v1/fleet/users on a schedule to detect user changes, or use Fleet's audit log (available in Fleet Premium) for change tracking.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Fleet does not implement a SCIM 2.0 endpoint as of the current documentation.
• IdP-driven user provisioning is not natively supported; users must be created via the REST API or UI.
• SSO (SAML) is supported for authentication but does not include JIT provisioning or SCIM sync.

Three automation scenarios cover the majority of lifecycle use cases.

To provision a service account: POST /api/v1/fleet/users/admin with api_only: true - note this endpoint creates the user silently with no email sent, unlike POST /api/v1/fleet/invites which requires SMTP and sends an invitation.

To audit all role assignments: paginate GET /api/v1/fleet/users and inspect global_role and teams client-side, since the list endpoint offers no server-side role filter.

To offboard a user: GET /api/v1/fleet/users to resolve id by email, then DELETE /api/v1/fleet/users/{id} - deletion is immediate, irreversible, and invalidates active sessions;

there is no soft-delete or suspend state.

Confirm removal with a follow-up GET expecting a 404.

If SSO JIT provisioning is active, a deleted user will be automatically recreated on their next SSO login - deletion alone is insufficient for full deprovisioning in SSO environments.

Programmatically provision an API-only service account

1. Authenticate as an Admin: POST /api/v1/fleet/login with admin credentials to get a token.
2. Create the API-only user: POST /api/v1/fleet/users/admin with {name, email, password, global_role: 'observer', api_only: true}.
3. Log in as the new user: POST /api/v1/fleet/login with the new user's credentials to retrieve its dedicated API token.
4. Store the token securely (e.g., in a secrets manager) and use it for all subsequent API calls.

Watch out for: api_only cannot be changed after creation. If you need a different type later, delete and recreate the user.

Bulk-list and audit all users and their roles

1. Authenticate as Admin and obtain a token.
2. GET /api/v1/fleet/users?page=0&per_page=100 to retrieve the first page of users.
3. Increment page parameter and repeat until the returned users array is empty.
4. For each user, inspect global_role and teams fields to audit role assignments.

Watch out for: There is no server-side filter by role on the list endpoint; all filtering must be done client-side after retrieval.

Remove a departed employee's access

1. GET /api/v1/fleet/users to find the user's id by email.
2. DELETE /api/v1/fleet/users/{id} to immediately remove the user.
3. If the user had active sessions, their tokens are invalidated upon deletion.
4. Verify removal by attempting GET /api/v1/fleet/users/{id} - expect a 404 response.

Watch out for: Deletion is irreversible. There is no disable/suspend state; the only option is full deletion.

The primary integration trap is the global_role / teams mutual exclusivity: a PATCH that sets global_role will silently drop all team memberships, and vice versa. Scripts that update one field without reading and preserving the other will corrupt role state without returning an error.

A secondary trap is the two distinct user-creation flows - POST /api/v1/fleet/users/admin (direct, no email) versus POST /api/v1/fleet/invites (email-based, requires SMTP, invite expiry applies) - which behave differently and are not interchangeable.

For teams building an identity graph via an MCP server with 60+ deep IT/identity integrations, the absence of user lifecycle webhooks is a structural limitation: Fleet emits no user.created or user.deleted events, so change detection requires scheduled polling of GET /api/v1/fleet/users or reliance on Fleet Premium's audit log.