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}. medoes not work with such a key, and neither does anything else outside the list. The error ispermission_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/sessionThe 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/sessionDELETE /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/sessionThe response has the value ok. After this the key gives the error
authentication_failed.
To delete another key, make the request with that key.