PowerShell client users are highly recommended to use the HTTPS endpoints instead of HTTP. The Windows .NET Framework does not propagate the original request headers as a security measure. While the HTTP endpoints will redirect (via a 301 status code) to the corresponding HTTPS endpoints, PowerShell will drop the authorization token headers during the redirect, resulting in a 401 Unauthorized Error as a response.
Aside from a few API endpoints that are considered standard operations and are required for general usage, a secret key must be provided along with the API key on each request to gain access to the rest of the API methods.
Only one secret key is created per account and it is automatically generated when you enable or disable the the API through the account management page.
- To access your account keys, firstly login and then click on your account name in the top right of the website, then click Manage… from the drop down list.
- Click on your account name to bring up the account management page.
- Finally, enable API Access and refresh the page to have your secret key generated.
There are 2 ways to form the API request headers for
Authorizationrequest header is formed by concatenating your Service API Key and your Secret Key:
Authorization: Token token=”[Service API Key][Secret Key]”
Authorizationrequest header can also be formed with the basic access authentication method, where the username is supplied with the
Service API Key, and the password will be your
curl -H 'Authorization: Token token="[Service API Key][Secret Key]"' https://app.upguard.com/api/v2/nodes.json
curl --user [Service API Key]:[Secret Key] https://app.upguard.com/api/v2/nodes.json
API v1 vs. v2
While v1 and v2 of the UpGuard API are similar, and in many cases identical, there are important differences to consider when choosing to use one or the other.
Parts of the v1 API have been deprecated. The v1 API as a whole is no longer under active development, and will not receive new features or bugfixes.
The v2 API is capable of working with parts of UpGuard that v1 is not. For example, v2 has support for Connection Manager Groups and Policies.
Some URLs have changed for more consistent behavior across the API. For example, the Connection Manager API index is queried at
- The structure of JSON data returned by API endpoints may differ
between v1 and v2.
- Sometimes this is additive, and should not affect code written for the v1 API. For example, the v2 Nodes API returns the same data as v1, with extra data fields added.
- However, some endpoints return very different data. For example, the User Tasks API provides different JSON structures depending on the API version.
- Some v1 API endpoints have been deprecated. Deprecated v1 APIs are marked as such in the API endpoint documentation.
If you are considering a migration, please consult the documentation for each API endpoint that you require.
Because v1 of the API is deprecated, and does not include some of the functionality provided in v2, we encourage customers to use v2 for new development.
However, v1 is not end-of-life and will continue to work normally for the foreseeable future. If v1 provides the features that you require, it is not necessary to migrate at this time.
If you are planning to use the API for development work or for an extended period of time, using an app such as Postman can help you save time by saving queries and nicely formatting (and presenting) JSON responses.
HTTP Status Code Summary
|200||OK||Everything worked as expected|
|201||Created||A new record was successfully created after a POST request|
|204||No Content||A record was successfully updated after a PUT request|
|400||Bad Request||Submitting malformed JSON or bad syntax|
|401||Unauthorized||No valid API key provided|
|403||Forbidden||Parameters were valid but request failed due to lack of permissions. (e.g. Trying to show details of a node that is not yours.)|
|422||Unprocessable Entity||The request is logically incorrect - often missing a required parameter. (e.g. Not specifying a policy_id when asking for a list of scripts)|
|500-504||Server Errors||Server errors|
Ignoring self-signed Certificates
If your appliance is using a self-signed certificate, you may need to implicitly trust the server before making an API request. Simply add this to the script in question, and all web requests will ignore the self-signed certificate.