> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/commons/api-keys.md). # 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`](/docs/navixy-api/user-api/resources/commons/user.md#post-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](/docs/navixy-api/user-api/resources/commons/user/session.md#post-user-session-renew). * 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. {% hint style="danger" %} 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. {% endhint %} For how to send a key with a request, see [Platform authentication](/docs/navixy-api/user-api/authentication.md). ## API key object ## The ApiKey object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"ApiKey":{"type":"object","description":"A credential equivalent to a session hash but with unlimited lifetime, intended for one integration each.\n\n**Treat it as a secret.** It can perform almost any action on the account, and it travels in cleartext, so calls must go over HTTPS.","properties":{"hash":{"type":"string","description":"The key itself, 32 characters. Send it as `Authorization: NVX `.","minLength":32,"maxLength":32},"create_date":{"type":"string","description":"When the key was created."},"title":{"type":"string","description":"Title given to the key, so it can be told apart from the others."}}}}}} ``` ## 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`](/docs/navixy-api/user-api/resources/commons/user.md#post-user-auth) with a login and password. An API key cannot be used to manage API keys. *** ## Create API key > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Account and platform","description":"Platform-level resources shared across the account, such as the plugins that change how other calls behave."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"ApiKey":{"type":"object","description":"A credential equivalent to a session hash but with unlimited lifetime, intended for one integration each.\n\n**Treat it as a secret.** It can perform almost any action on the account, and it travels in cleartext, so calls must go over HTTPS.","properties":{"hash":{"type":"string","description":"The key itself, 32 characters. Send it as `Authorization: NVX `.","minLength":32,"maxLength":32},"create_date":{"type":"string","description":"When the key was created."},"title":{"type":"string","description":"Title given to the key, so it can be told apart from the others."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/api/key/create":{"post":{"tags":["Account and platform"],"summary":"Create API key","description":"Create an API key, and return it.\n\nAn 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.\n\n**Up to 20 keys per account.** Give each one a meaningful title so they can be told apart.\n\n**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.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"apiKeyCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title for the new key. Not empty, printable characters only, up to 255 characters.","minLength":1,"maxLength":255}},"required":["title"]}}}},"responses":{"200":{"description":"The new API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/ApiKey"}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 268: the account already has the maximum of 20 API keys.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Account and platform","description":"Platform-level resources shared across the account, such as the plugins that change how other calls behave."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/api/key/delete":{"post":{"tags":["Account and platform"],"summary":"Delete API key","description":"Revoke an API key. Anything using it stops working immediately.\n\n**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.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"apiKeyDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"The API key to delete. Not empty.","minLength":1}},"required":["key"]}}}},"responses":{"200":{"description":"API key deleted","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Account and platform","description":"Platform-level resources shared across the account, such as the plugins that change how other calls behave."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"ApiKey":{"type":"object","description":"A credential equivalent to a session hash but with unlimited lifetime, intended for one integration each.\n\n**Treat it as a secret.** It can perform almost any action on the account, and it travels in cleartext, so calls must go over HTTPS.","properties":{"hash":{"type":"string","description":"The key itself, 32 characters. Send it as `Authorization: NVX `.","minLength":32,"maxLength":32},"create_date":{"type":"string","description":"When the key was created."},"title":{"type":"string","description":"Title given to the key, so it can be told apart from the others."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/api/key/list":{"post":{"tags":["Account and platform"],"summary":"List API keys","description":"List the API keys of the current account.\n\n**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.\n\nCallable with an empty body. Also accepts GET.","operationId":"apiKeyList","responses":{"200":{"description":"The API keys","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/user-api/resources/commons/api-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.