Skip to main content

Authenticate with an API key

To call the Netwrix Privilege Secure for Discovery API, you exchange an API key for an access token, and then you send the token with each request. This page shows the exchange with curl. The API base path is /api/v1, and every request uses HTTPS.

The product doesn't publish an OpenAPI or Swagger document for this API. The pages in this section describe the endpoints that customers use most.

Prerequisites​

  • An API key. See Create and manage API keys.
  • The ID of a user that is linked to the key. In the interface, hover over the ID in the Linked Users column of Configure > API Keys to see which user it belongs to.
  • A computer with curl that can reach the server.

Get an access token​

Send the API key and the user ID to POST /api/v1/api-keys/auth. This request needs no other credentials.

curl --request POST "https://<server-fqdn>/api/v1/api-keys/auth" \
  --header "Content-Type: application/json" \
  --data '{"token": "<api-key>", "userId": "<user-id>"}'

The response contains the access token, its expiration time in UTC, and the scopes of the key. An empty scopes list means the key has the All API's permission.

{
  "message": "Access granted.",
  "token": "<access-token>",
  "expires": "2026-10-21T14:28:49.000Z",
  "scopes": []
}

By default, an access token is valid for 8 hours, and the expires value shows the exact time. An administrator can change the lifetime with the Token Expiration Seconds setting under Configure > Services, from 300 seconds (5 minutes) to 604800 seconds (1 week). After it expires, repeat the request to get a new token. Each successful request also updates the Last Accessed value of the key.

Send an authenticated request​

Send the access token in the X-Access-Token header. The API also accepts the Authorization: Bearer <access-token> header. The following request lists the first 20 computers.

curl --request GET "https://<server-fqdn>/api/v1/computers?limit=20" \
  --header "X-Access-Token: <access-token>"

The token carries the role of the linked user. A request that the role doesn't allow returns the status 403.

Troubleshoot authentication errors​

StatusMessageCause and fix
400Invalid userIdThe request has no userId, or the user isn't linked to the key. Use the ID of a linked user.
403This token is not a valid API keyThe key is revoked, or the product doesn't know it. Create a new key.
401jwt malformedThe value of token isn't a key, for example because the copy cut off part of it. Copy the secret again.
403Requested user not foundThe linked user no longer exists. Create a key for another user.
401No auth token providedAn API request has no access token. Add the X-Access-Token header.
403Scope not allowed by tokenA key with the Registration permission called an endpoint other than POST /api/v1/computers/register. Use a key with the All API's permission.
403User does not have access to this resource.The role of the linked user doesn't allow the endpoint. Link the key to a user with a suitable role.

If curl reports a certificate error, install the certificate chain of the server on the computer that runs curl, or pass the certificate authority file with --cacert. Don't use the --insecure option, because it turns off certificate verification.