REST API FAQs

Answers to common questions about N-able N-central REST APIs.

Q: How can I get support or report issues?

If you require assistance or have a technical issue, contact Technical Support using N-able's N-ableMe at https://me.n-able.com/ and click Support from the top menu.

You will need to be logged in to N-ableMe

You can also call at:

  • Americas: 1-855-679-0817

  • EMEA: +44 (0) 1382 309040

  • APAC: +61 (0) 2 8412 4905

Q: What data formats are supported in the requests and responses?

The supported data format for requests and responses is JSON.

Q: What are the rate limits for the REST API endpoints?

Each endpoint has a specific rate limit applied to it. The rate limitation is applied on concurrent calls per end point. In other words, the limit is on the number of concurrent calls allowed for each endpoint.

The range of allowed concurrent calls is anything between 3 to 50. If a limit is reached a 429 HTTP access code will be returned. The caller is responsible for handling this status code and implement a retry mechanism. See Rate Limiting for more details.

Q: What is included in the Scheduled Task API?

There are methods included that enable the API user to: 

  • Create a task that runs a script now against a target device
  • Get general info about a scheduled taskID, like the associated parentID, Name, Type, customerID, deviceIDs, and whether or not the task is enabled.

  • Get the detailed status of a scheduled taskID for each device associated with that task, like deviceID/name and the status of the task for each device (success, fail, etc.) .

Q: Is the information that we were getting from the deviceAssetInfoExportDevice SOAP API method (e.g. patch, service) available through REST APIs?

Not yet. This information will become available in future versions of the API Service.

Q: What type of information does Device Tasks API get?

This GET method returns information about the task ID, task name, and status for a device.

Q: Can I remotely pass a script through the Runscript API?

No, not at this time. The script or automation must be contained within the script and software repository.

Q: The Runscript API has 3 mandatory fields. Where do I find these in the N-central UI?

remoteExecutionItemId: The remote execution ID can be found in the scripts and software repository located under the column head called repositoryID.

customerId: The customer ID can be found under the SO > Administration > Customers. Locate the customer ID under the "access code" column.

deviceId: The device ID is not listed in the N-central but you can use the API called /api/devices to list and filter through the device IDs.

Q: What to do when I get the "End time cannot be before start time" error when trying to run a script via APIs?

This indicates there is a clock drift on the target device. Check the local time on the target device and make sure it is correct.

Q: How can I revoke an access token or refresh token?

The only way to revoke an access token or refresh token is to re-generate the JWT (User API Token) in the UI. Re-generating the JWT token will result in the previous JWT token and all access/refresh tokens associated with it to be revoked.

The revocation can take up to 5 mins after the generation of the new token.

Q: Why is the toggle to enable some scripts and AMPs disabled?

Look at the “Repository ID” of the script. If it is a number under 2000, it is considered a “bundled” script that comes by default with N-central. Because the IDs of these scripts are pre-defined and known, for security purposes these scripts cannot be enabled for use through REST APIs. In order to invoke these scripts using REST APIs, clone them and use the new script.

If the “Repository ID” is not a low number and the toggle is disabled, this would be because the current user does not have enough permission to enable that script. A user with higher privilege needs to enable the script for REST API use.

Q: How can I get the ID of a script/AMP I want to invoke via REST APIs?

To get the ID of a script/AMP, login to the UI and navigate to Configuration > Scheduled Tasks > Script/Software Repository and fetch the ID from “Repository ID” column. In order to invoke that script with the /scheduled-tasks/direct endpoint , the “Enable API” toggle should be switched to “ON”.

There is no endpoint to fetch the IDs of scripts programmatically. This is intentional and by design to harden the security around the REST API functionality.

Q: Are there metrics around REST API endpoint usage?

At the moment there are no metrics around REST API endpoint usage. There is a way to get information about the usage however: A user that has access to Administration Utilities → View logs can download the api-service.log file and parse the log file for the occurrence of the endpoint in question.

Q: Is there a test environment available?

If your N-central instance has been upgraded to 2023.9, or later, the REST API functionality is enabled by default. If you are using an older version of N-central and would like to try out this functionality, or if you are interested in previewing new APIs in upcoming releases, please reach out to headnerds@n-able.com for access to a test environment.

Q: What roles/permissions should I assign to the account dedicated to making API calls?

The best practice is to dedicate a specific account to making API calls and making sure the “API User Only” check box in the Account > API Access tab is checked. This way the API-only user will not be able to use their account to log in to the UI and can only access the REST APIs. It is also best practice to assign the least amount of privilege (roles and permissions) to the account you dedicate for making REST API calls. To determine what the minimum roles/permissions for using a specific API endpoint is, use an existing role with the least amount of privilege that you know is capable of performing the same action through the UI.

Q: What is the default expiry for the access token and refresh token? Is it possible to create an access token or refresh token with shorter life than the default?

The default expiry for the access token is 1 hour. The default expiry for the refresh token is 24 hours.

You can request a shorter expiration period but not a longer one. To decrease the expiry time for the tokens use the following HTTP headers in your /auth/authenticate or /auth/refresh endpoint:

X-ACCESS-EXPIRY-OVERRIDE : 120s

X-REFRESH-EXPIRY-OVERRIDE: 4h

The unit of time should follow the number and be one of ‘s', ‘m’ or 'h’.

Q: I can exchange my JWT token with an access token using /api/auth/authenticate successfully but when I call an API endpoint I get the 500 Internal Error.

If the error reads something like this:

{ "status": 500, "message": "[ID=73861a4e-cb98-435b-beb9-8466916950d4] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: Device List - The deserialized response indicates a non-success status code." }

Try updating the password on the API account. If the API account has a password that has expired, this will prevent the API account from calling API endpoints. Create a new password for the API account and then create a new JWT token and redo the exchange.

Q: What are different levels for task ID and how are they used?

There are distinct levels associated with a created task: SYSTEM, CUSTOMER, and DEVICE.

  • When a task is generated, the returned taskID is linked to the SYSTEM level. However, behind the scenes, three separate tasks are created, each having the same name but different IDs.

  • When utilizing the /devices/<taskID>/scheduled-tasks endpoint, the ID in the response body is at DEVICE level and corresponds to the customer under which device is created.

The /scheduled-tasks/<taskID>/status endpoint allows the use of any task ID from every level.

The /scheduled-tasks/<taskID>/details endpoint cannot use a task ID from the DEVICE level; it can only be used for task IDs from the SYSTEM and CUSTOMER levels.

To retrieve the task ID from other levels:

  1. use the /scheduled-tasks/<taskIdDeviceLevel> endpoint

  2. use the parentId to inquire about the status or details of a task

Q: Where can I find some sample code for the REST APIs?

Here’s a list of GitHub repository and links to sample code for the N-central REST APIs:

This documentation may contain references to third party software or websites. N-able has no control over third party software or content and is not responsible for the availability, security, or operation, of any third-party software. If you decide to utilize a release involving third-party software, you do so entirely at your own risk and subject to the applicable third party’s terms and conditions of the use of such software. No information obtained by you from N-able or this documentation shall create any warranty for such software.

Q: I am getting FORBIDDEN: ScriptNotRunnableException: Remote Execution Task Add - selected Scheduled Task script with id 'NNN' is not executable via Rest API

This message is returned where the script was not selected for API use. To enable API execution for the script, go to Configuration > Scheduled Tasks > Script/Software Repository and make sure the button in the “Enable API” column is turned ON for the script.

If you experience difficulty enabling this option, please refer to Q: Why is the toggle to enable some scripts and AMPs disabled?

Q: Which port are the REST API endpoints on and can we move them? If not, how can we block them?

The APIs are served on port 443. Currently there is no mechanism to move the APIs to a custom port.

In order to block/restrict access to REST API endpoints, the following URL paths can be used as a filter:

  • Endpoints: /api/*

  • Swagger documentatio pages: /api-explorer/*