API keys

Long-lived credentials for integrations, used in place of a user session hash.

An API key is the credential an integration authenticates with. It works exactly like a session hash obtained from user/auth, except that it never expires.

That difference matters in several ways:

• A key survives the user logging out or changing their password.

• A key never needs renewing.

• A key means the integration never handles the account's username and password.

• A key can be revoked on its own the moment it is suspected of being compromised.

• Each integration can hold its own key, so revoking one leaves the others working.

• Keys have their own rate-limit counter, so an integration exhausting its limit does not block the account's ordinary users.

An account can hold up to 20 keys. Give each one a meaningful name, because the name is what distinguishes them later. Keys can also be created from the web interface, which is the recommended route for a person rather than a program.

Do not publish an API key anywhere. A key can perform almost any action in the account it belongs to. Make API calls over HTTPS only, because the key travels in clear text.

For how to send a key with a request, see Platform authentication.

API key object

API actions

API base path: /api/key.

These operations are available only to the master user, and only with a standard session obtained from user/auth with a login and password. An API key cannot be used to manage API keys.

---

Create API key

post

/api/key/create

Create an API key, and return it.

An API key is the same thing as a session hash but with unlimited lifetime. It survives a logout and a password change, needs no renewal, does not require storing a login and password, can be revoked on its own, and has a separate rate-limit counter from ordinary user requests.

Up to 20 keys per account. Give each one a meaningful title so they can be told apart.

A standard session hash is required, and an API key is rejected with error 4, "User or API key not found or session ended", which is misleading because the key itself is valid. Get a session hash from user/auth. Master users only, since the operation needs the admin right.

Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body

titlestring · min: 1 · max: 255Required

Title for the new key. Not empty, printable characters only, up to 255 characters.

Responses

200

The new API key

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

402

Error 268: the account already has the maximum of 20 API keys.

application/json

403

Error 4: the session is invalid, or a non-standard session such as another API key was used. Error 13: the caller is not a master user.

application/json

default

Error response object

application/json

post/api/key/create

POST /v2/api/key/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "title": "text"
}

{
  "success": true,
  "value": {
    "hash": "text",
    "create_date": "text",
    "title": "text"
  }
}

Errors

These errors come in addition to the general error codes:

• 4 - User or API key not found or session ended, when the hash is invalid or belongs to a non-standard session such as another API key.

• 13 - Operation not permitted, when the caller is not a master user.

• 268 - Over quota, when the account already holds the maximum of 20 API keys.

---

Delete API key

post

/api/key/delete

Revoke an API key. Anything using it stops working immediately.

A standard session hash is required, and an API key is rejected with error 4, "User or API key not found or session ended", which is misleading because the key itself is valid. Get a session hash from user/auth. Master users only, since the operation needs the admin right.

Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body

keystring · min: 1Required

The API key to delete. Not empty.

Responses

200

API key deleted

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 4: the session is invalid, or a non-standard session such as another API key was used. Error 13: the caller is not a master user.

application/json

default

Error response object

application/json

post/api/key/delete

POST /v2/api/key/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "key": "text"
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

• 4 - User or API key not found or session ended, when the hash is invalid or belongs to a non-standard session such as another API key.

• 13 - Operation not permitted, when the caller is not a master user.

• 201 - Not found in the database, when no key has the given hash.

---

List API keys

post

/api/key/list

List the API keys of the current account.

A standard session hash is required, and an API key is rejected with error 4, "User or API key not found or session ended", which is misleading because the key itself is valid. Get a session hash from user/auth. Master users only, since the operation needs the admin right.

Callable with an empty body. Also accepts GET.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Responses

200

The API keys

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 4: the session is invalid, or a non-standard session such as another API key was used. Error 13: the caller is not a master user.

application/json

default

Error response object

application/json

post/api/key/list

POST /v2/api/key/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "list": [
    {
      "hash": "text",
      "create_date": "text",
      "title": "text"
    }
  ]
}

Errors

These errors come in addition to the general error codes:

• 4 - User or API key not found or session ended, when the hash is invalid or belongs to a non-standard session such as another API key.

• 13 - Operation not permitted, when the caller is not a master user.