NGINX Docs
    • DevCentral

      Connect & learn in our hosted community

    • MyF5

      Your key to everything F5, including support, registration keys, and subscriptions

    • NGINX

      Learn more about NGINX Open Source and read the community blog

Documentation Powered by ReDoc

NGINX One Console Spec (v1)

Download OpenAPI specification:Download

The API Reference documentation for NGINX One Console

Authentication

BearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Data Plane Key

The DataPlaneKey object represents a secure token required to establish a connection between your NGINX instances and NGINX One. As a fundamental security measure, the data plane key ensures that only trusted NGINX instances can register and communicate with NGINX One.

Data plane keys expire after one year. This is the default setting if you don't specify an expiration time when you create a key. If necessary, you can update the data plane key later to extend its expiration.

Revoking a data plane key will disconnect the associated NGINX instances from NGINX One.

IMPORTANT Data plane keys are not saved and are displayed only once when you generate them. You should save this key in a secure location for future reference.

List all data plane keys

Returns a list of data plane keys for your tenant namespace. This list provides important information such as each key's name, when it was created, and when it will expire.

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameDataPlaneKeys)
Items Enum: "name" "status" "object_id"

Filter options for data plane keys; used in conjunction with other filter parameters having the same array length.

When filtering on status, only the following filter_values are supported:

  • revoked
  • expired
  • valid
filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 2,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Bulk operation on multiple data plane keys

Performs bulk operation on one or more data plane keys, only delete is supported.

Request Body schema: application/json
Array ()
action
required
string (BulkRequestAction)
Default: "modify"
Enum: "create" "modify" "delete"

Bulk action to perform:

  • create creates a new object given all required elements.
  • modify updates one or more elements of an existing object.
  • delete removes the existing object.
object_id
required
string <object_id> (DataPlaneKeyObjectID) ^key_.*

A globally unique identifier for the data plane key.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Create a data plane key

Creates a unique data plane key that you can use to register NGINX instances with NGINX One.

IMPORTANT: Save the data plane key somewhere secure for reference. The key is displayed only once and cannot be retrieved again.

Request Body schema: application/json
name
required
string [ 1 .. 128 ] characters

Give the data plane key a name so you can tell it apart from others.

expires_at
string <date-time>

Set an expiration date and time for the data plane key in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. If an expiration date isn't specified, the key will expire one year after it's created.

You can use the Update a data plane key endpoint to extend the expiration date. It's not possible to update the expiration date once the data plane key has expired.

Responses

Request samples

Content type
application/json
{
  • "name": "my-data-plane-key",
  • "expires_at": "2023-12-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "expires_at": "2023-12-01T00:00:00Z",
  • "key": "<data plane key>",
  • "name": "my-data-plane-key",
  • "object_id": "key_Tet21AeYTHCj7taOwVfzyw"
}

Delete a data plane key

Deletes a data plane key.

path Parameters
data_plane_key_id
required
string <object_id> (DataPlaneKeyObjectID) ^key_.*

A globally unique identifier for the data plane key.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "request_id": "string",
  • "timestamp": "string",
  • "detail": "string"
}

Retrieve a data plane key

Retrieves the details for an existing data plane key.

path Parameters
data_plane_key_id
required
string <object_id> (DataPlaneKeyObjectID) ^key_.*

A globally unique identifier for the data plane key.

Responses

Response samples

Content type
application/json
{
  • "expires_at": "2023-12-01T00:00:00Z",
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z",
  • "revoked": false,
  • "name": "my-data-plane-key",
  • "object_id": "key_wN3IhLCmR3qmwybG_6ptEg",
  • "instances_count": 3
}

Update a data plane key

Updates an existing data plane key.

You can update the data plane key's name or extend its expiration date. It's not possible to update the expiration date for a data plane key that has expired.

path Parameters
data_plane_key_id
required
string <object_id> (DataPlaneKeyObjectID) ^key_.*

A globally unique identifier for the data plane key.

Request Body schema: application/json
name
string [ 1 .. 128 ] characters

Give the data plane key a new name so you can tell it apart from others.

expires_at
string <date-time>

Adjust the expiration date and time for the data plane key in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

It's not possible to update the expiration date once the data plane key has expired.

Responses

Request samples

Content type
application/json
{
  • "name": "my-data-plane-key",
  • "expires_at": "2023-12-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "expires_at": "2023-12-01T00:00:00Z",
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z",
  • "revoked": false,
  • "name": "my-data-plane-key",
  • "object_id": "key_wN3IhLCmR3qmwybG_6ptEg",
  • "instances_count": 3
}

Revoke a data plane key

Revoke an existing data plane key.

IMPORTANT: When you revoke a data plane key, all NGINX instances registered with this key will be disconnected from NGINX One.

path Parameters
data_plane_key_id
required
string <object_id> (DataPlaneKeyObjectID) ^key_.*

A globally unique identifier for the data plane key.

Responses

Response samples

Content type
application/json
{
  • "expires_at": "2023-12-01T00:00:00Z",
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z",
  • "revoked": false,
  • "name": "my-data-plane-key",
  • "object_id": "key_wN3IhLCmR3qmwybG_6ptEg",
  • "instances_count": 3
}

Instances

The Instance object represents an active NGINX installation. You can access detailed information about each NGINX instance, including its configuration analysis, security advisories, and operational status.

List all instances

Returns a list of all NGINX instances, providing details such as:

  • Unique identifiers for each instance
  • Timestamps for key actions (like registration and last report)
  • Information about the NGINX build
  • Version of the NGINX Agent
query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameInstances)
Items Enum: "hostname" "nginx_version" "os_version" "instance_status" "cert_status" "cve_severity" "config_recommendation" "key_object_id" "system_id" "object_id"

An array of strings indicating which fields to filter by (for example, hostname, nginx_version). This parameter works in conjunction with filter_values and filter_ops.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_instances
Array of strings
Items Enum: "hostname" "status" "last_reported"

Sort instances by enumerate value(s). Ordinal position determines primary, secondary, etc.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Bulk operation on multiple instances

Performs bulk operation on one or more NGINX instances, only delete is supported.

Request Body schema: application/json
Array ()
action
required
string (BulkRequestAction)
Default: "modify"
Enum: "create" "modify" "delete"

Bulk action to perform:

  • create creates a new object given all required elements.
  • modify updates one or more elements of an existing object.
  • delete removes the existing object.
object_id
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete an instance

Deletes an NGINX instance. Associations with certificates will be cleaned up.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "request_id": "string",
  • "timestamp": "string",
  • "detail": "string"
}

Retrieve an instance

Retrieves the details for an NGINX instance, including

  • Hostname
  • System status
  • Timestamps of key actions (registration, last reported, etc.)
  • NGINX build information
  • Certificate data
  • Operating system version
  • NGINX Agent version
  • Config Sync Group membership details
path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
{
  • "agent_version": "v2.30.3",
  • "certs":
    [
    ],
  • "hostname": "4d116619f106",
  • "key": "key_wN3IhLCmR3qmwybG_6ptEg",
  • "last_reported": "2023-12-06T22:37:24.120114Z",
  • "nginx_build":
    {
    },
  • "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437",
  • "os":
    {
    },
  • "registered_at": "2023-12-06T22:37:24.120114Z",
  • "status": "unknown",
  • "system_id": "b2c0b6a8-8b6a-3a8f-a541-17d8899c119a",
  • "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw"
}

Retrieve an instance's configuration details

Returns the configuration details for an NGINX instance, including:

  • Main configuration path
  • Details about configuration files
  • Details about auxiliary files
  • Details about deployed payloads of managed SSL certificates and keys
  • Unique identifiers
path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Apply partial updates to an instance's configuration

Applies the specified partial updates to an existing NGINX configuration. This endpoint accepts additive updates to NginxConfig. To delete files, omit the file.contents field. This method compares the provided config_version with the current NGINX instance configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update. Before publishing, use the PATCH /instances/{instanceObjectID}/config-report endpoint to generate an analysis report for the modified configuration.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
{
  • "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba",
  • "created_at": "2024-05-14T20:36:06.272704Z",
  • "modified_at": "2024-05-14T20:36:06.272704Z",
  • "object_id": "pub_vfr5Oqv-AhxGzyqTXW-Ubw",
  • "status": "pending"
}

Publish a configuration to an instance

Publishes a new or updated NGINX configuration to the specified instance. If no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten. Before publishing, use the PUT /instances/{instanceObjectID}/config-report endpoint to generate an analysis report for the provided configuration. You can specify payloads in the request to deploy managed certificates and keys to the dataplane. Include file paths for each payload component.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
{
  • "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba",
  • "created_at": "2024-05-14T20:36:06.272704Z",
  • "modified_at": "2024-05-14T20:36:06.272704Z",
  • "object_id": "pub_vfr5Oqv-AhxGzyqTXW-Ubw",
  • "status": "pending"
}

Retrieve an analysis report for an instance's configuration

Analyzes the configuration of an NGINX instance and returns a detailed report. The report includes insights, identified issues, and recommendations for optimizing and troubleshooting.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate an analysis report for the provided modified configuration

Analyzes the provided partial updates to an existing NGINX configuration and generates a report detailing potential issues along with optimization suggestions. This analysis accounts for additive updates made to NginxConfig. To delete files, omit the file.contents field. This method compares the provided config_version with the current NGINX instance configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the PATCH /instances/{instanceObjectID}/config endpoint.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Generate an analysis report for the provided configuration

Returns an analysis report for the provided NGINX configuration. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the PUT /instances/{instanceObjectID}/config endpoint.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves the stored NGINX configurations for an instance

Returns a list of all configurations for a NGINX instance. Only the last 5 are kept on the NGINX One Console for a NGINX instance.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an instance's configuration details

Returns the configuration details for an NGINX instance, including:

  • Main configuration path
  • Details about configuration files
  • Details about auxiliary files
  • Unique identifiers
path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

instanceConfigurationObjectID
required
string <object_id> (NginxConfigObjectID) ^nc_.*

A globally unique identifier for the NGINX instance configuration.

Responses

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Retrieve an instance's security advisories (CVEs)

Retrieves a list of the security advisories (CVEs) for an NGINX instance.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the publications for an instance

Returns a list of all publications for a NGINX instance.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a publication for an NGINX instance.

Returns a specific publication for an NGINX instance. Only 5 previous entries of Publication are kept for each NGINX instance.

path Parameters
instanceObjectID
required
string <object_id> (InstanceObjectID) ^inst_.*

A globally unique identifier for the NGINX instance.

publicationObjectID
required
string <object_id> (PublicationObjectID) ^pub_.*
Example: pub_72pGHoGsSICL_THZrs964g

A globally unique identifier for a Publication.

Responses

Response samples

Content type
application/json
{
  • "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba",
  • "created_at": "2024-05-14T20:36:06.272704Z",
  • "modified_at": "2024-05-14T20:36:06.272704Z",
  • "object_id": "pub_vfr5Oqv-AhxGzyqTXW-Ubw",
  • "status": "pending"
}

Retrieve a summary for all instances

Retrieves a comprehensive summary for all NGINX instances, which includes details such as:

  • Certificate status and associations
  • Operating system details
  • Version of the NGINX Agent
  • Overall system status

Responses

Response samples

Content type
application/json
{
  • "certs":
    [
    ],
  • "os":
    [
    ],
  • "nginx_versions":
    [
    ],
  • "statuses":
    {
    },
  • "cves":
    [
    ],
  • "recommendations":
    [
    ]
}

Config Sync Groups

The ConfigSyncGroups object represents a NGINX config sync group where Instances are grouped to have same configuration. You can access detailed information about each NGINX config sync group, including its configuration analysis and operational status.

List all config sync groups

Returns a list of all NGINX config sync groups, providing details such as:

  • Name of the config sync group
  • List of instance with details
  • Version of the NGINX configuration that's expected to be on all listed instances
  • Status of apply configuration operation
  • Timestamp of last reported action
query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameConfigSyncGroups)
Items Enum: "name" "config_status" "object_id"

An array of strings indicating which fields to filter by (for example, name, config_status). This parameter works in conjunction with filter_values and filter_ops.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_config_sync_groups
Array of strings
Items Value: "name"

Sort config sync groups by enumerate value(s). Ordinal position determines primary, secondary, etc.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Bulk operation on multiple config sync groups

Performs bulk operation on one or more config sync groups, only delete is supported.

Request Body schema: application/json
Array ()
action
required
string (BulkRequestAction)
Default: "modify"
Enum: "create" "modify" "delete"

Bulk action to perform:

  • create creates a new object given all required elements.
  • modify updates one or more elements of an existing object.
  • delete removes the existing object.
object_id
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Create an NGINX config sync group

Create NGINX config sync group with a unique name to identify it within the tenant namespace.

Request Body schema: application/json
name
required
string [ 1 .. 256 ] characters

A name to uniquely identify the Nginx config sync group in a given tenant namespace.

Responses

Request samples

Content type
application/json
{
  • "name": "my-nginx-config-sync-group"
}

Response samples

Content type
application/json
{
  • "name": "my-nginx-config-sync-group",
  • "object_id": "csg_Tet21AeYTHCj7taOwVfzyw"
}

Delete an NGINX config sync group

Delete a NGINX config sync group from the NGINX One console. You can delete a config sync group, only if it contains no NGINX instances.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "request_id": "string",
  • "timestamp": "string",
  • "detail": "string"
}

Retrieve an NGINX config sync group

Retrieve the details for an NGINX config sync group, including:

  • name
  • Instances and details of each instance
  • Timestamp of last reported action
  • NGINX config version on the config sync group
  • Certificate summary referenced by config sync group members
  • NGINX config sync operation status
  • Last config sync group publication operation status
path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
{
  • "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw",
  • "name": "test-config-sync-group",
  • "last_reported": "2023-12-06T22:37:24.120114Z",
  • "config_status": "in_sync",
  • "config_version": "uvR3F2TQGm18jnl7bpaGw",
  • "instances":
    [
    ],
  • "certs":
    [
    ]
}

Retrieve a config sync group's configuration details

Returns the configuration details for a NGINX config sync group, including:

  • Main configuration path
  • Details about configuration files
  • Details about auxiliary files
  • Unique identifiers
path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Apply partial updates to config sync group's configuration

Applies the specified partial updates to an existing NGINX configuration. Details:

  • This endpoint accepts additive updates to NginxConfig.
  • To delete files, omit the file.contents field.
  • This method compares the provided config_version with the current NGINX config sync group configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update.
path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Publish a configuration to NGINX config sync group

Publishes a new or updated NGINX configuration to the specified config sync group. If no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Retrieve an analysis report for the configuration of an NGINX config sync group

Analyzes the configuration of an NGINX config sync group and returns a detailed report. The report includes insights, identified issues, and recommendations for optimizing and troubleshooting.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate an analysis report for the configuration of the modified NGINX config sync group

Analyzes the provided partial updates merging with an existing configuration of an NGINX config sync group. Generates a report detailing potential issues along with optimization suggestions. This analysis accounts for additive updates made to NGINX configuration. To delete files, omit the file.contents field. This method compares the provided config_version with the current NGINX config sync group's configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the PATCH /config-sync-groups/{configSyncGroupObjectID}/config endpoint.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Generate an analysis report for the configuration of the NGINX config sync group

Returns an analysis report for the configuration of the NGINX config sync group. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the PUT /config-sync-groups/{configSyncGroupObjectID}/config endpoint.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details the NGINX config sync group

Returns the configuration details for an NGINX config sync group, including:

  • Main configuration path
  • Details about configuration files
  • Details about auxiliary files
  • Unique identifiers
path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

configSyncGroupConfigurationObjectID
required
string <object_id> (NginxConfigObjectID) ^nc_.*

A globally unique identifier for the NGINX config sync group configuration.

Responses

Response samples

Content type
application/json
{
  • "aux": [ ],
  • "conf_path": "/etc/nginx/nginx.conf",
  • "configs":
    [
    ],
  • "object_id": "string",
  • "payloads":
    [
    ]
}

Retrieves stored NGINX configurations for a NGINX config sync group

Returns a list of all configurations for a NGINX config sync group. Only the last 5 are kept on the NGINX One Console for a NGINX config sync group.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the publications for the NGINX config sync group

Returns a list of publications for a NGINX config sync group, providing details such as:

  • Current status along with reason(s) including the target instance object, cause and relevant message
  • Configuration version
path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the publications for the NGINX config sync group, providing details such as: * Current status along with reason(s) including the target instance object, cause and relevant message * Configuration version

Returns a publication for a NGINX config sync group.

path Parameters
configSyncGroupObjectID
required
string <object_id> (configSyncGroupObjectID) ^csg_.*

A globally unique identifier for the NGINX config sync group.

publicationObjectID
required
string <object_id> (PublicationObjectID) ^pub_.*
Example: pub_72pGHoGsSICL_THZrs964g

A globally unique identifier for a Publication.

Responses

Response samples

Content type
application/json
{
  • "config_version": "fc3bb4b50c145b3ca5c5d1342be5ec0718eeb9bb84f8d53c5734b6b8",
  • "created_at": "2024-05-23T21:57:13.048285Z",
  • "modified_at": "2024-05-23T21:57:13.048285Z",
  • "object_id": "pub_UPV8jXFwSgm1vHQJCvLD1w",
  • "status": "failed",
  • "status_reasons":
    [
    ]
}

Certificates

The Certificates object in the NGINX One console represents an SSL certificate, covering both managed and unmanaged types. You can view essential details like issuer, expiration status, and the instances or config sync groups where each certificate is deployed.

List all SSL certificates

Returns a paginated list showing metadata for every SSL certificate.

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameCertificates)
Items Enum: "name" "management" "type" "subject_name" "status" "object_id"

Filter options for certificates; used in conjunction with other filter parameters having the same array length.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_certificates
Array of strings
Items Enum: "name" "subject_name" "not_before" "not_after"

Sort certificates by enumerate value(s). Ordinal position determines primary, secondary, etc.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 2,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Create an SSL certificate

Creates a new SSL certificate with an optional name. You must supply the certificate's content in base64-encoded PEM format. Any warnings will be displayed only upon creation of the certificate object, and is not retrievable after it is created.

Request Body schema: application/json
required
object (CertificateContent)

Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.

name
string [ 1 .. 128 ] characters

A name for the certificate, making it identifiable among others.

Responses

Request samples

Content type
application/json
{
  • "name": "example-ca-bundle",
  • "content":
    {
    }
}

Response samples

Content type
application/json
{
  • "name": "example-cert_key",
  • "object_id": "cert_Tet21AeYTHCj7taOwVfzyw",
  • "management": "managed",
  • "type": "cert_key",
  • "status": "valid",
  • "subject_name": "www.example.com",
  • "not_before": "2023-08-10T16:59:15Z",
  • "not_after": "2024-08-14T16:59:15Z",
  • "warnings": "The provided private key does not match the certificate's signing key.",
  • "certs_count": 1,
  • "certs":
    [
    ],
  • "key":
    {
    },
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z"
}

Delete an SSL certificate

  • Deletes a managed SSL certificate from the NGINX One console. This operation is disabled for unmanaged certificates, as they get cleaned up automatically when they are not used in any NGINX configuration.
  • An optional flag deleteFromDataPlanes when set to true, can be used to remove the certificate from data plane instances to where it was deployed.
    • Deleting from data planes triggers publications on either instances or Config Sync Groups. After the managed cert object is deleted from NGINX One Console, a PublicationBulkResponse is returned along with status code 202, indicating whether an error occurred while issuing a publication to a data plane target.
    • If this cert is not associated with any data plane, status code 204 is returned when deleteFromDataPlanes set to true.
path Parameters
certificateObjectID
required
string <object_id> (CertificateObjectID) ^cert_.*

A globally unique identifier for the certificate.

query Parameters
deleteFromDataPlanes
boolean

Flag indicating whether the certificate should be deleted from its associated data planes.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an SSL certificate

Retrieves the details for an SSL certificate, including:

  • Object ID that uniquely identifies this certificate object
  • SSL certificate type (managed or unmanaged by NGINX One Console)
  • Certificate type (whether it is a CA bundle or a certificate-key pair)
  • Subject name of the leaf certificate, or the soonest-expiring CA in a bundle
    • This subject name will be the DNS name in the SAN extension of the certificate. If not present, it will be the certificate's common name
  • Status of the certificate (valid, expiring, expired)
  • Validity period, if applicable to multiple certificates
  • Metadata for each public certificate if multiples are provided
  • Private key metadata, if available
path Parameters
certificateObjectID
required
string <object_id> (CertificateObjectID) ^cert_.*

A globally unique identifier for the certificate.

Responses

Response samples

Content type
application/json
{
  • "name": "example-cert_key",
  • "object_id": "cert_Tet21AeYTHCj7taOwVfzyw",
  • "management": "managed",
  • "type": "cert_key",
  • "status": "valid",
  • "subject_name": "www.example.com",
  • "not_before": "2023-08-10T16:59:15Z",
  • "not_after": "2024-08-14T16:59:15Z",
  • "warnings": "The provided private key does not match the certificate's signing key.",
  • "certs_count": 1,
  • "certs":
    [
    ],
  • "key":
    {
    },
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z"
}

Update an SSL certificate

Updates public certificates, private keys, or both. This endpoint can also be used to update a Certificate Authority (CA) bundle.

path Parameters
certificateObjectID
required
string <object_id> (CertificateObjectID) ^cert_.*

A globally unique identifier for the certificate.

Request Body schema: application/json
name
string [ 1 .. 128 ] characters

A name for the certificate, making it identifiable among others.

object (CertificateUpdateContent)

Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.

Responses

Request samples

Content type
application/json
{
  • "name": "example-cert-object",
  • "content":
    {
    }
}

Response samples

Content type
application/json
{
  • "name": "example-cert_key",
  • "object_id": "cert_Tet21AeYTHCj7taOwVfzyw",
  • "management": "managed",
  • "type": "cert_key",
  • "status": "valid",
  • "subject_name": "www.example.com",
  • "not_before": "2023-08-10T16:59:15Z",
  • "not_after": "2024-08-14T16:59:15Z",
  • "warnings": "The provided private key does not match the certificate's signing key.",
  • "certs_count": 1,
  • "certs":
    [
    ],
  • "key":
    {
    },
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z"
}

List SSL certificate deployments

Returns a paginated list showing all the deployments for a SSL certificate and assigned file path(s).

path Parameters
certificateObjectID
required
string <object_id> (CertificateObjectID) ^cert_.*

A globally unique identifier for the certificate.

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameCertificateDeployments)
Items Enum: "name" "association_type" "deployment_status"

Filter options for certificate deployments; used in conjunction with other filter parameters having the same array length.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_certificate_deployments
Array of strings
Items Value: "name"

Sort certificate deployments by enumerate value(s). Ordinal position determines primary, secondary, etc.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 2,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Parse and validate an SSL certificate

Parses and validates an SSL certificate. It checks the provided PEM files and verifies that the public certificates follow the correct X.509 format. If the certificate cannot be parsed, an error will be returned. Otherwise, as long as the certificate is parsable, a 200 OK status will be returned even if there are issues such as mismatched private keys or expired certificates. Details of any issues found will be shown in the "warnings" field of the response.

Request Body schema: application/json
required
object (CertificateContent)

Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.

name
string [ 1 .. 128 ] characters

A name for the certificate, making it identifiable among others.

Responses

Request samples

Content type
application/json
{
  • "name": "example-ca-bundle",
  • "content":
    {
    }
}

Response samples

Content type
application/json
{
  • "name": "example-cert_key",
  • "object_id": "cert_Tet21AeYTHCj7taOwVfzyw",
  • "management": "managed",
  • "type": "cert_key",
  • "status": "valid",
  • "subject_name": "www.example.com",
  • "not_before": "2023-08-10T16:59:15Z",
  • "not_after": "2024-08-14T16:59:15Z",
  • "warnings": "The provided private key does not match the certificate's signing key.",
  • "certs_count": 1,
  • "certs":
    [
    ],
  • "key":
    {
    },
  • "modified_at": "2023-11-01T00:00:00Z",
  • "created_at": "2023-10-01T00:00:00Z"
}

CVEs

The CVEs object represents the security advisories published for all the F5 products supported by NGINX One.

List of all CVEs affecting the instances

Returns a list of all CVEs that affect at least one instance under the tenant

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_cves
Array of strings
Items Enum: "instance_count" "severity" "cve_id" "published_at"

Sort CVEs by the number of instances affected by that CVE.

Responses

Response samples

Content type
application/json
{
  • "total": 101,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Retrieve NGINX CVE details

Retrieve CVE details

path Parameters
nginxCVEID
required
string ^\d{4}-\d{4,19}$

A globally unique identifier for NGINX CVE.

Responses

Response samples

Content type
application/json
{
  • "id": "CVE-ID",
  • "severity": "medium",
  • "info": "Memory disclosure in the ngx_http_mp4_module",
  • "instances_impacted": 0,
  • "published_at": "2022-10-19T00:00:00Z",
  • "detail": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-ID",
  • "impacted_products":
    [
    ]
}

Retrieve the instances impacted by a CVE

Retrieves a list of the instances impacted by a security advisory.

path Parameters
nginxCVEID
required
string ^\d{4}-\d{4,19}$

A globally unique identifier for NGINX CVE.

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_cve_impacted_instances
Array of strings
Items Enum: "hostname" "status"

Sort the Instances that are affected by a CVE

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Events

Get a list of system events in the NGINX One console.

Retrieve system events.

Retrieves a list of the system events.

query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterNameEvents)
Items Value: "object_id"

An array of strings indicating which fields to filter by (for example, hostname, object_id). This parameter works in conjunction with filter_values and filter_ops.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

Responses

Response samples

Content type
application/json
{
  • "total": 101,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Retrieve specific event.

Retrieve a specific event using the event object_id.

path Parameters
eventObjectID
required
string <object_id> (EventObjectID) ^event_.*

A globally unique identifier for an event.

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2024-02-04T09:57:36.088757764Z",
  • "type": "instance_cleanup",
  • "object_id": "event_-uvR3F2TQGm18jnl7bpaGw",
  • "affected_object_id": "inst_-uvR3F2TQGm18jnl7bpaGw",
  • "message": "ip-170.0.1 deleted after age out period of 3 hours, last seen 2023-08-07T09:57:36.088757764Z"
}

Staged Configs

List all staged configs

Returns a list of all NGINX staged configs, providing details such as:

  • Name and object_id of staged config
  • Created and modified timestamps
query Parameters
paginated
boolean
Default: true

A boolean indicating if the results should be presented as a paginated list. Defaults to true. When set to false, the results are returned as a condensed, non-paginated list.

limit
integer >= 0

An integer that specifies the maximum number of items to be returned. Setting this to 0 will result in no items being returned, but a total count will still be provided. This parameter is not applicable if paginated is false.

offset
integer >= 1

An integer that specifies the starting position of the results, starting at 1. This parameter is not applicable if paginated is false.

filter_fields
Array of strings (FilterStagedConfigs)
Items Enum: "name" "object_id"

An array of strings indicating which fields to filter by (for example, name). This parameter works in conjunction with filter_values and filter_ops.

filter_ops
Array of strings (FilterOperands)
Items Value: "IN"

An array of strings defining the operands for filtering, to be used in conjunction with filter_fields and filter_values. All filter parameters must have matching array lengths. Currently, the only supported operand is "IN".

filter_values
Array of strings
Example: filter_values=value1|value2|value3

An array of strings containing the keywords for filtering. Multiple keywords can be chained using the | character. Ensure this parameter's array length matches those of filter_fields and filter_ops for effective filtering. The total length of the filter string should not exceed 1024 characters.

sort_dir
string
Enum: "Ascending" "Descending"

Sorting direction for the criteria and the resulting collection returned. Defaults to descending if not specified.

sort_staged_configs
Array of strings
Items Value: "name"

Sort staged configs by enumerate value(s). Ordinal position determines primary, secondary, etc.

Responses

Response samples

Content type
application/json
{
  • "total": 10,
  • "count": 1,
  • "start_index": 1,
  • "items_per_page": 100,
  • "items":
    [
    ]
}

Create an NGINX staged config

Create NGINX staged config with a unique ID to identify it within the tenant namespace.

Request Body schema: application/json
name
required
string (StagedConfigName) [ 1 .. 256 ] characters ^[^\s]+$

A name to identify the NGINX staged config.

object (NginxConfigRequest)

Details of an NGINX configuration, the main configuration path, and the configuration directories.

Responses

Request samples

Content type
application/json
{
  • "name": "my-nginx-staged-config",
  • "config":
    {
    }
}

Response samples

Content type
application/json
{
  • "name": "my-nginx-staged-config",
  • "object_id": "sc_Tet21AeYTHCj7taOwVfzyw"
}

Delete an NGINX staged config

Delete a NGINX staged config from the NGINX One console.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "request_id": "string",
  • "timestamp": "string",
  • "detail": "string"
}

Retrieve an NGINX staged config meta

Retrieve the meta details for an NGINX staged config.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Responses

Response samples

Content type
application/json
{
  • "object_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "cert_summary":
    {
    }
}

Retrieve an NGINX staged config

Retrieve the details for an NGINX staged config.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "config":
    {
    }
}

Apply partial updates to staged config

Applies the specified partial updates to an existing NGINX staged config Details:

  • This endpoint accepts additive updates to NginxConfig. Base nginx.conf file must always be provided along with additives.
  • To delete files, omit the file.contents field.
  • config_version is used to ensure the requested patch is applied against the same version.
path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Request Body schema: application/json
name
string (StagedConfigName) [ 1 .. 256 ] characters ^[^\s]+$

A name to identify the NGINX staged config.

object (NginxConfigRequest)

Details of an NGINX configuration, the main configuration path, and the configuration directories.

Responses

Request samples

Content type
application/json
{
  • "config":
    {
    }
}

Response samples

Content type
application/json
{
  • "object_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "cert_summary":
    {
    }
}

Replace existing state

Completely replaces existing staged config with payload of new request.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Request Body schema: application/json
name
required
string (StagedConfigName) [ 1 .. 256 ] characters ^[^\s]+$

A name to identify the NGINX staged config.

required
object (NginxConfigRequest)

Details of an NGINX configuration, the main configuration path, and the configuration directories.

Responses

Request samples

Content type
application/json
{
  • "name": "my-nginx-staged-config",
  • "config":
    {
    }
}

Response samples

Content type
application/json
{
  • "object_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "cert_summary":
    {
    }
}

Retrieve an analysis report for the NGINX staged config

Analyzes the NGINX staged config and returns a detailed report. The report includes insights, identified issues, and recommendations for optimizing and troubleshooting.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate an analysis report for the modified NGINX staged config

Analyzes the provided partial updates merging with an existing configuration of an NGINX config sync group. Generates a report detailing potential issues along with optimization suggestions. This analysis accounts for additive updates made to NGINX configuration. To delete files, omit the file.contents field. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the PATCH /staged-configs/{stagedConfigObjectID}/config endpoint.

path Parameters
stagedConfigObjectID
required
string <object_id> (StagedConfigObjectID) ^sc_.*

A globally unique identifier for the NGINX staged config.

Request Body schema: application/json
conf_path
required
string [ 1 .. 4096 ] characters

The full path to the main NGINX configuration file. This corresponds to the --conf-path parameter used in the NGINX binary.

required
Array of objects (DirectoryRequestWithFileContent)

An array of directories containing NGINX configuration files.

config_version
string

A hash that uniquely identifies the contents of the config object. Can be used to detect change when updating the NginxConfig.

Array of objects (DirectoryRequestWithFileContent)

An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are provided, they become the authoritative source of non-NGINX configuration content. Please ensure the provided contents are complete, missing files that are referenced in the NGINX configuration can cause NGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of publish.

Array of objects (NginxConfigPayloads)

An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy them onto the data plane instance.

  • If the type is managed_certificate or managed_key, you need to specify an object_id.
    • The object_id must represent a managed certificate object, or a 400 Bad Request is returned.
    • The contents field is optional and is ignored if included.
  • The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want them to be managed by NGINX One Console, inline_content and inline_secret can be used for certificates or keys, respectively. When you retrieve certificate deployment details, only the file paths of managed certificates and keys will be shown.
  • If you use inline_content and inline_secret in your NGINX configuration, the NGINX One Console will detect them. When they are used as SSL directives of the NGINX configuration for certificates and keys, the certificates will be listed as unmanaged_certificate in the certificate deployment details.

Responses

Request samples

Content type
application/json
{
  • "config_version": "string",
  • "conf_path": "/etc/nginx/nginx.conf.",
  • "configs":
    [
    ],
  • "aux":
    [
    ],
  • "payloads":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Metrics

Retrieve system metrics for instances with series limit

Returns (up to 10,000) system metrics for NGINX instances with series limit based on query parameters.

You can filter metrics by name and timestamp, aggregate metrics over a configurable period of time, and group metrics by dimension.

Request Body schema: application/json
required
Array of objects (MetricNames)

Specify the metrics you want details for.

Usage:

  • List multiple metrics as json objects.
    • You can aggregate metrics with avg, sum, min, max, rate.
  • Metrics with aggregates require a start_time.
  • If you combine aggregated and non-aggregated metrics in a single query, any group_by clause applies only to the aggregated metrics.
series_limit
required
integer

Sets the maximum number of series that can be returned.

Notes:

  • Always returns an additional series with a dimension named all, aggregating the values of all metrics included in the results.
  • A series with a dimension named other may be returned, aggregating the values of metrics not included in the results.
group_series_by
required
string (MetricDimension)
Default: "display_name"
Enum: "display_name" "file_path" "parent_hostname" "instance_object_id" "location_zone" "mount_point" "namespace" "network_interface" "nginx_id" "server_zone" "system_id" "tenant" "csg_object_id" "mode" "state" "io_direction" "status_range"

Static list of all metric dimensions.

  • display_name - The display name of the NGINX instance.
  • file_path - Path to a desired file.
  • parent_hostname - The hostname of the NGINX Plus instance.
  • instance_object_id - Instance Object ID is the unique identifier for an Instance registered with NGINX One Console.
  • location_zone - The name of an HTTP location zone.
  • mount_point - A filesystem mount point.
  • namespace - The Namespace associated with the metric data.
  • network_interface - A server network interface.
  • nginx_id - The unique identifier of an nginx instance running on the data plane.
  • server_zone - The name of an HTTP or Stream server zone.
  • system_id - The unique identifier of the the operating system where nginx-agent is running.
  • tenant - The Tenant associated with the metric data.
  • csg_object_id - Config Sync Group Object ID is the unique identifier for a Config Sync Group registered with NGINX One Console.
  • mode - Variant value associated with metric system.cpu.time.
  • state - Variant value associated with metrics system.filesystem.usage, system.memory.usage.
  • io_direction - Variant value associated with metric system.network.io.
  • status_range - Variant value associated with metric nginx.http.response.status.
Array of objects (MetricFilters)

Filter results based on dimension operations against one or more values.

Usage:

  • Format as one or more predicates by providing all required elements.
    • dimension: The dimension name you want to filter on.
    • operator: The possible operators (=, !=, <, <=, >, >=, in, not) you can use for comparison or condition checking.
    • value: Case sensitive value of the dimension to filter against.

For more complex filtering:

  • Specify a predicate for logical expressions (AND,OR).
  • Use a wildcard * in the value for matching partial values.
start_time
string (StartTime)

Sets the beginning of the time period for your metrics query (inclusive).

Usage:

  • start_time is required if end_time is specified.
  • If start_time isn't provided, the API returns the latest metrics.
  • start_time is required for aggregated metrics in order to calculate the resolution (granularity).

Time can be specified in two ways:

  • Using ISO 8601 format. For example, "2019-08-07T09:57:36.088757764Z".
  • As an offset from the current time. For the offset, use + or -, followed by a number and the appropriate time unit. The time unit can can be y (years), M (months), w (weeks), d (days), h (hours), m (minutes), or s (seconds). Example of an offset: "now-3h" (3 hours before now).
end_time
string (EndTime)

Sets the end point for the time period for your metrics query (non-inclusive).

Usage:

  • Must be greater than start_time.
  • If start_time is specified and end_time is not, end_time defaults to the current time.

Time can be specified in two ways:

  • Using ISO 8601 format. For example, "2019-08-07T09:57:36.088757764Z".
  • As an offset from the current time. For the offset, use + or -, followed by a number and the appropriate time unit. The time unit can can be y (years), M (months), w (weeks), d (days), h (hours), m (minutes), or s (seconds). Example of an offset: "now-3h" (3 hours before now).
resolution
string

Specifies the level of granularity for time series data in your results. Applicable only for endpoints that return time series data.

Usage:

  • Specify as a string with a number followed by a unit of time, such as y (years), M (months), w (weeks), d (days), h (hours), m (minutes) or s (seconds).
  • Metrics in names must be aggregated.
  • start_time is required.
  • If resolution is not set, the API returns the maximum resolution (end_time - start_time).
dimensions
Array of strings (TopXMetricDimensions)
Items Enum: "display_name" "file_path" "parent_hostname" "instance_object_id" "location_zone" "mount_point" "namespace" "network_interface" "nginx_id" "server_zone" "system_id" "tenant" "csg_object_id" "mode" "state" "io_direction" "status_range"

List additional dimensions to include in the response for each metric series. The dimension specified by group_series_by will be included by default.

object (OrderSeriesBy)

Sort order of the metric series in your results.

Usage:

  • Provide all required elements.
    • direction: The sorting direction either desc or asc.
    • aggregate: The aggregating function.

Responses

Request samples

Content type
application/json
{
  • "start_time": "now-1h",
  • "end_time": "now",
  • "resolution": "1m",
  • "metrics":
    [
    ],
  • "series_limit": 1,
  • "group_series_by": "instance_object_id"
}

Response samples

Content type
application/json
{
  • "query_metadata":
    {
    },
  • "metrics":
    [
    ]
}

Settings

Configuration option for different aspect of NGINX One service. You can set NGINX Instance cleanup preferences.

Retrieve settings

Retrieves settings for NGINX Instance cleanup

Responses

Response samples

Content type
application/json
{
  • "age_out_duration": 3
}

Update settings

Update settings for NGINX Instance cleanup

Request Body schema: application/json
age_out_duration
required
integer <int32> [ 0 .. 720 ]
Default: 3

Specify the age of unavailable NGINX instances for clean up. NGINX instances older than this value in hours will be deleted automatically. Events related to automatically deleted NGINX instances will show up in /events API. '0' value disables the automatic clean up of unavailable NGINX instances.

Responses

Request samples

Content type
application/json
{
  • "age_out_duration": 3
}

Response samples

Content type
application/json
{
  • "age_out_duration": 3
}