Create an API key for your own software

Make a key that your own software or an integration uses to read and write Nova on your organization's behalf, choose what it can do and when it expires, then revoke it when it is no longer needed.

In the sidebar, open Administration, then choose API & Connected Apps under Integrations & API. The page address is /settings/org/integrations/api. The API keys tab opens first.

A key on this tab is for your own software or an integration, such as a nightly copy of paid invoices into your bookkeeping tool. It works for one organization only, does only what you tick, and can be revoked at any time. For an outside assistant such as ChatGPT, connect it instead: see Connect ChatGPT, Claude or another assistant to Nova.

Before you start

• Your admin has to give your role the permission to manage keys.
• A key that can only read is safer than one that can write; tick the smallest set the software needs.

Steps

1. Press Create API key. The Create API key panel opens.
2. Under About this key, type a Name that says which software uses it, such as "Accounting export".
3. Under What is it for?, say what the key does so the next admin knows whether it is still needed.
4. Choose an Accountable person. They get the expiry warnings and anything the key asks a person to approve.
5. Under What it can do, search for the thing you want the software to touch, then press a button on its row: Read to look, Change to add and edit, Send and finish for things like sending an invoice, and Override or Administer where they appear. Press a row's arrow to pick one action at a time instead.
6. A button with a line through it is one you do not have yourself, so you cannot give it away. Hover it to read why.
7. If your organization has branches, tick the ones under Where it can work. Leave them all unticked to let the key work across every branch.
8. Choose when it Expires. 1 year is chosen for you; Never is available but a key that expires is safer.
9. If you want a cap or a second pair of eyes, open Advanced: addresses, rate limit, daily limit, approvals. Type a Daily action limit to cap how many changes it may make in a day, and pick actions under Ask a person first to have someone approve each use. Leave both empty and the key just gets on with it.
10. Press Create API key. Nova shows Your new API key.
11. Press the copy button beside the key and paste it into your software's settings. The Client id, the Token address and a ready-to-paste Try it command are shown there too. Press Done.

Warning: The key is shown once. If it is lost, replace it or revoke it and create another.

Before you press the button, read the sentence under the list: it says in plain words what the key will be able to do.

Changing a key later

1. On the key's row, press Edit.
2. Change whatever you need, then press Save changes.
3. If you changed what it can do, Nova lists what is being added and removed; press Save to confirm. The change takes effect on the key's next request.

Replacing a key without an outage

1. On the key's row, press Replace key.
2. Choose how long The old key keeps working for: 1 hour, 1 day, 1 week or Straight away.
3. Press Make a new key, copy the new key and update your software before the old one stops.

To revoke a key:

1. On the key's row, press Revoke.
2. Press Revoke to confirm. Anything using the key stops working right away, and the key cannot be turned back on.

What you see

• Each row shows the key's name, who looks after it, what it reads and changes, how many of its actions wait for approval, the last four characters of the key, when it was last used and when it expires. An expiry within a month is highlighted.
• While a replaced key is still in its overlap window, the row says when the old key stops working.
• Everything the software does with the key is written to the audit log under the key's name. See Read the audit log.
• A key can be given anything your organization can do, including deletes, voids, refunds and settings. Nova does not decide for you which of your own actions your software may take. The one limit is that a key never gets more than the person saving it has.

If something looks different

• Create API key is missing: your role cannot manage keys. Ask your admin.
• No API keys yet: nobody has created one for this organization.
• Your software says the key is invalid: it may have expired, been revoked, or been replaced and the overlap window has closed. Check the row, then create a new key.
• Your software gets a message about a missing permission: it names the exact permission to add. Press Edit on the key and search for it.
• Your software gets a message about needing approval: the action is on this key's Ask a person first list, or it is one of the few high-stakes actions that always need a person. Approve it on the Approvals tab of this page, or press Edit on the key and take the action off that list.
• Edit or Replace key is missing: your role cannot change keys. Ask your admin.