Credentials

Every datastore comes with one default API token, connect. It can back up, restore and prune, and it reaches the whole datastore. On the Credentials page of the datastore settings you can add more API tokens to the same datastore. Each token gets one role and one namespace. A client that uses the token can do only what the role allows, and only in that namespace and the namespaces below it.

Use one token per client. If a host is compromised, you delete its token, and every other client keeps working. Give each host the smallest role it needs: a Proxmox VE node that only writes backups does not need to read the backups of other nodes, and a restore host does not need to write.

Roles and what they allow

The roles are the standard Proxmox Backup Server roles, so they behave as in a Proxmox Backup Server that you run yourself.

"Own backups" are the backup groups that the token created itself. Proxmox Backup Server records the token as the owner of each group. So a DatastoreBackup token on one host cannot read or delete the backups of another host, even in the same namespace.

Create a token

Create the namespace first on the Namespaces settings page. Then open Credentials, click Add API token, and enter a name, a role, a namespace and an optional comment. Token names use 1 to 32 lowercase letters, digits, - and _. The names connect and names that start with restore are reserved. The token reaches the namespace you pick and every namespace below it. All namespaces gives access to the whole datastore.

The dashboard shows the token ID and the secret after you create the token. You can show the secret again later with Show secret in the table, and the connection dialog on the datastore page lets you pick the token when there is more than one.

Connect a client

In Proxmox VE, add the datastore as a Proxmox Backup Server storage as usual. Enter the token ID (for example user-…@pbs!pve-node-a) as Username and the secret as Password, and enter the namespace of the token in the Namespace field. The server, the datastore and the fingerprint are the same as for the default token. A Proxmox Backup Server that adds the datastore as a remote uses the token ID as Auth ID and the secret as Password.

Things to know

The default token connect does not see the backups of other tokens either. It sees only the groups it created itself. To restore a backup that a different token made, use a DatastoreReader token on that namespace or on the whole datastore.

A new secret takes effect at once. Every client that uses the old secret stops working until you enter the new one. Deleting a token has the same effect. The role and the namespace of a token cannot change: delete the token and create a new one.

Credentials work together with ACLs. An ACL limits from which networks a client can connect, and the token limits what the client can do once it is connected.