An API key gives access to an account. A login on the website is an API key too, which is why these endpoints are called session. Apps get their key through OAuth. How a key is sent with a request is on the first page.

Permissions#

A key has eight permissions, which are each on or off:

Permission What the key can do
filesystem_read List directories, read file information, download and search files
filesystem_write Upload, create directories, rename, move, delete, and change how files are shared
account_read See the account: user name, e-mail address, plan, usage and statistics
account_write Change account settings, the password and e-mail address included, and delete the account
session_read List the API keys of the account which can do no more than this key
session_write Create API keys which can do no more than this key
billing_read See invoices and transactions
billing_write Create invoices and change the plan

account_write gives full control over the account: whoever can change the password can log in, and a login has all permissions.

A key from a login on the website has all permissions. The filesystem permissions count for FTP and SFTP too, because those log in with an API key.

Directory limits#

A key can be limited to a list of directories. It then only works inside those directories:

  • Each directory in the list is a root of its own. Use its ID in the path: /filesystem/{id}/{path inside the directory}.
  • me does not work with such a key, and neither does anything else outside the list. The error is permission_denied.
  • A node can’t be moved from one directory in the list to another, because a rename stays inside one root.
  • With FTP the ID of the directory is the user name. SFTP always opens the home directory, so it does not work with a limited key.

A key without a list works everywhere.

The key object#

{
	"auth_key": "c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22",
	"creation_ip_address": "203.0.113.7",
	"user_agent": "curl/8.9.1",
	"app_name": "Backup script",
	"creation_time": "2026-10-02T15:04:05.123Z",
	"last_used_time": "2026-10-02T15:04:05.123Z",
	"valid_domains": ["nova.storage"],
	"current": false,
	"filesystem_read": true,
	"filesystem_write": true,
	"account_read": true,
	"account_write": false,
	"session_read": false,
	"session_write": false,
	"billing_read": false,
	"billing_write": false,
	"filesystem_dirs": ["6m6r7854Ubzt491q4AJuCb"]
}
Field Meaning
auth_key The key itself. Keep it secret
creation_ip_address The IP address which created the key
user_agent The User-Agent header of the request which created the key
app_name The name which was given to the key
creation_time When the key was created
last_used_time When the key was last used
valid_domains The domain names of Nova on which the key works
current In a list of keys: whether this is the key the list was asked for with
The eight permissions See Permissions
filesystem_dirs IDs of the directories the key is limited to. Empty is no limit

POST /user/session#

Creates a new API key for the account.

Permission: session_write.

Parameter Required Value
app_name no A name for the key, up to 50 characters
The eight permissions no true or false each
filesystem_dirs no JSON list of directory IDs, 100 at most. "me" in the list is the home directory. An empty list takes the limit away

The new key starts with the permissions and the directories of the key which creates it. The parameters change that. So to make a key which can do less, only the permissions it should lose have to be sent as false.

A key can’t create a key which can do more than it can itself. That is a permission it does not have, or a directory outside its own list. The error is key_permission_denied.

This creates a key which can only read and write in one directory:

curl -u ":$NOVA_KEY" \
    -d app_name="Backup script" \
    -d account_read=false -d account_write=false \
    -d session_read=false -d session_write=false \
    -d billing_read=false -d billing_write=false \
    -d 'filesystem_dirs=["6m6r7854Ubzt491q4AJuCb"]' \
    https://nova.storage/api/user/session

The response has status 201 and the new key.

GET /user/session#

Lists the API keys of the account.

Permission: session_read.

The response is a list of key objects. A key only sees the keys which it could have created itself: the ones with the same permissions or less. A key with all permissions and no directory limit sees all of them.

curl -u ":$NOVA_KEY" https://nova.storage/api/user/session

DELETE /user/session#

Deletes the key which the request was made with. This is how a program logs out.

Every key can do this, there is no permission for it.

curl -u ":$NOVA_KEY" -X DELETE https://nova.storage/api/user/session

The response has the value ok. After this the key gives the error authentication_failed.

To delete another key, make the request with that key.