#REST API

Every page in the JumpServer web UI is backed by a REST API under /api/v1/. The same API lets you automate asset and account management, read audit records, and integrate JumpServer with external systems. The API schema is generated from the backend code, so the reference at /api/docs/ on your own host is always the authoritative source for paths and fields.

#API documentation

Schema endpoints require an authenticated session or token.

#Authentication

Obtain a bearer token with the administrator credentials:

curl -s -X POST https://jumpserver.example.com/api/v1/authentication/auth/ \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "********"}'

The response contains a token field. The token expires; the lifetime is controlled by the TOKEN_EXPIRATION setting. Access keys are created under Profile > Access Keys, and the secret is shown only once. See Access Keys.

#Organization context

Most objects are scoped to an organization. Send the organization UUID in the X-JMS-ORG header:

curl -s https://jumpserver.example.com/api/v1/users/users/?limit=5 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-JMS-ORG: 00000000-0000-0000-0000-000000000002'

Without the header, the request uses the default organization. In the community edition only the default organization is available; in the enterprise edition the token user must also be a member of the requested organization.

#Endpoint groups

The API is grouped by module. The main groups are:

/api/v1/index/ returns the API index, which is useful for discovering the enabled modules on a host.

#Pagination and filtering

List endpoints use limit/offset pagination:

• limit sets the page size, capped by MAX_PAGE_SIZE (1000 by default).
• offset skips records and is used to walk through pages.
• Requests that do not ask for a page return at most DEFAULT_PAGE_SIZE (200 by default) records.
• q performs a text search and order sorts the result, for example ?order=date_created.

curl -s 'https://jumpserver.example.com/api/v1/assets/assets/?limit=10&offset=0&order=name' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-JMS-ORG: <organization-id>'

#Permissions

API requests are checked against the same RBAC permissions as the web UI. A user can never do more through the API than through the UI: authorizations, ACLs, and role permissions all apply. A missing permission returns 403; an object outside the active organization is not visible at all. Read-only endpoints are the safest place to start when building an integration.

#Related topics

• Integrations
• Roles and permissions
• Access Keys