Overview: NGINX Instance Manager REST API
Legacy 'nms' references
Some commands, file paths, and configuration references still usenms
due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.
Introduction
NGINX Instance Manager provides a REST API that uses standard authentication methods, HTTP response codes, and verbs. You can use the API to manage both NGINX Instance Manager and the NGINX instances running on your systems.
Object model
The NGINX Instance Manager REST API allows you to manage both NGINX Instance Manager and NGINX instances programmatically. The API provides the following features:
- View metrics and information about data plane host systems and NGINX instances.
- View and edit NGINX configurations.
- Save NGINX configurations for future deployment.
- Analyze saved and current configurations for syntactic errors.
- Publish configurations to NGINX instances.
- Scan the network to find unmanaged NGINX instances.
- Manage certificates.
- Create users, roles, and role permissions to manage RBAC.
API reference documentation
You can access the NGINX Instance Manager API documentation from the web interface:
- Log in to the FQDN of your NGINX Instance Manager host.
- Select API Documentation from the Launchpad menu.
- On the left menu, select NIM and Platform API.
Usage
You can use tools such as curl
or Postman to interact with the NGINX Instance Manager API.
You can find the NGINX Instance Manager API URLs in the following format: https://<NMS_FQDN>/api/platform/<API_VERSION>
.
Note:
When making API calls by usingcurl
, Postman, or any other tool, include your authentication information with each call. Also include a-k
to bypass TLS/SSL verification.
Alternatively, in the API Reference docs, you can also use the “Try it Out” function. Since you’re already logged into the NGINX Instance Manager platform, the “Try it Out” function automatically includes authentication credentials.
To do so, take the steps below:
- Select the endpoint and action that you want to send. For example:
POST /infrastructure/workspaces
. - Select the Try it Out button.
- If the endpoint accepts parameters, replace the placeholder examples in the request body with your desired values.
- Select the Execute button to send the request.
- When the request completes, the response appears in the user interface.
Authentication
To use the NGINX Instance Manager API, you need to use one of the following authentication methods:
- Basic authentication
- JSON Web Token (JWT)
Basic authentication
To use basic authentication for API requests, include your base64-encoded credentials as a “Basic” token in the “Authorization” header. To create the base64-encoded credentials, run the following command:
echo -n <username>:<password> | base64
Once you’ve generated the credentials, you can include them in your API request. Here’s how to do it with curl
:
curl -X GET "https://<NIM_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Basic <base64_encoded_credentials>"
In this example, replace <NIM_FQDN>
with your NGINX Instance Manager’s fully qualified domain name and <API_VERSION>
with the API version you want to use.
Security consideration
While basic authentication is an option for API requests, it comes with security risks: credentials are sent as base64-encoded text, which is not secure encryption. If the data is intercepted, the encoding can be easily reversed. For production environments, where security is critical, we strongly recommend switching to OpenID Connect (OIDC).
JSON Web Token
If your organization is using OIDC, you will be prompted to log in with your Identity Provider the first time you attempt to reach an API. After authenticating, you can request a JWT to use in subsequent API calls.
Note:
The means of requesting a token varies according to the Identity Provider; if you’re not sure which provider your organization uses, check with your system administrator or technical support team.
Once you have a JWT, set it up as a “Bearer”
curl -X GET "https://<NIM_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Bearer <access token>"
Protect sensitive data
To protect your system and data, follow these security practices:
JWTs: Treat JSON Web Tokens (JWTs) as sensitive data. Store them securely and delete them after use to prevent unauthorized access.
Shell history: Commands with JWTs or passwords are saved in plain text in your shell history. After running such commands, clear the history to protect credentials. For example:
- Edit your shell history file (such as ~/.bash_history or ~/.zsh_history) to remove specific commands.
- Use
history -c
to clear all shell history in bash or zsh.
Errors and response codes
NGINX Instance Manager uses standard HTTP response codes to indicate whether an API request succeeds or fails. Codes in the 2xx
range mean the request succeeded. Codes in the 400
range mean the request failed due to the reason(s) indicated in the response message. Common reasons for 4xx
responses are:
- Requests where required information is missing.
- Lack of or incorrect authentication credentials.
- Requests that refer to resources that do not exist or are in use by other resources.
HTTP Status Codes
Response Code | Meaning |
---|---|
200 | Success: The request was received. |
201 | Success: Created the requested resource. |
202 | Success: The request was accepted and configuration is in process. |
204 | Success: Deleted the requested resource. |
400 | Bad Request: Required information is missing or incorrectly formatted. |
401 | Unauthorized: You are not logged in or do not have permission to access the requested resource. |
404 | Not found: The requested resource does not exist. |
409 | Conflict: The requested resource already exists or is referenced by another resource. |
Encoding
The NGINX Instance Manager API expects and returns JSON-formatted data by default.
All JSON data must be encoded using UTF-8. If you don’t specify a media type in an API call, the API uses application/json
by default.
Pagination
Top-level NGINX Instance Manager API endpoints support fetching information about multiple resources (“lists”). These requests can return large data sets (for example, GET /events
and GET /instances
). You can control the size of the data set returned and navigate through pages by sending additional calls.
Parameters
Name | Format | Type | Description | Default value |
---|---|---|---|---|
page | integer | query | The page number to retrieve. | 1 |
pageToken | string | query | A transactional token used for pagination. The token ensures consistent query results across requests. | N/A |
pageSize | integer | query | The number of items returned per page. The maximum value is 100. If pageSize=0 , pagination is disabled, and all results are returned. |
100 |
Versioning
Each major version of the NGINX Instance Manager API is backward-compatible with previous releases of the same version. Any backward-incompatible changes result in a new major version.
The version is represented in the <version>
part of the API URI.
For example, to use a v2 API, send requests to:
https://<NIM>/api/platform/v2
When a new version is required, we release it for the entire API. You won’t see a mix of v1 and v2 objects in the same API.