canonical: https://jentic.com/apis/pbs.proxmox.com/pbs-proxmox

# Pbs Proxmox Proxmox Backup Server API

Proxmox Backup Server API provides management of backup infrastructure including user access control, authentication, datastore operations, and system administration. It supports user and token management with role-based permissions, two-factor authentication configuration, OpenID Connect integration, and realm-based directory synchronization. The API runs on the PBS host at port 8007 and uses cookie-based authentication with CSRF token protection.

## For AI agents

Manage backup server users, access tokens, permissions, two-factor authentication, and realm-based directory sync for Proxmox Backup Server instances.

## Scope

Does not handle VM provisioning, network configuration, or storage pool creation - use for backup server access control and user management only.

## Capabilities

- Create and manage user accounts with role-based access control and permissions
- Generate and rotate API tokens scoped to specific users for automation
- Configure two-factor authentication (TFA) for user accounts
- Authenticate via OpenID Connect with configurable realm providers
- Synchronize user directories from external realms (LDAP, Active Directory)
- Manage access control lists (ACLs) with path-based permission assignments
- Monitor active datastore operations and their status

## Use cases

### Backup Server User Management

Create, update, and manage user accounts on Proxmox Backup Server for team access to backup infrastructure. The API supports listing users, creating new accounts, updating profiles, and deleting decommissioned accounts. Each user can be assigned to a realm (PAM, OpenID, LDAP) and given specific roles that control what datastores and operations they can access.

Example prompt: Create a new user 'backup-agent@pbs' with admin role via POST `/access/users`, then generate an API token for that user via POST `/access/users/{userid}/token/{token-name}`

### API Token Automation

Generate scoped API tokens for automated backup workflows. Tokens inherit the permissions of the parent user and can be individually revoked without affecting the user's interactive access. This enables CI/CD pipelines, monitoring systems, and backup orchestration tools to authenticate without sharing user passwords.

Example prompt: List all tokens for user 'admin@pam' via GET `/access/users/{userid}/token`, then create a new token named 'monitoring' with read-only scope

### Access Control Configuration

Define granular permissions for users and tokens across datastores and system resources. The ACL system uses path-based permission assignments where each entry maps a user or token to a role on a specific resource path. This enables multi-tenant backup environments where each team can only access their designated datastores.

Example prompt: Retrieve the current ACL entries via GET `/access/acl`, then add a new entry granting 'DatastoreUser' role to 'backup-agent@pbs' on path '/datastore/vm-backups' via PUT `/access/acl`

### AI Agent Backup Infrastructure Management via Jentic

AI agents use the Proxmox Backup Server API through Jentic to manage users, rotate tokens, and configure permissions on PBS instances. Jentic handles the cookie-based authentication and CSRF token injection so agents can automate backup infrastructure operations without managing session state directly.

Example prompt: Search Jentic for 'manage Proxmox backup users', load the schema for GET `/access/users`, and execute to retrieve all configured user accounts with their roles

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/access/users` | List all users on the backup server |
| POST | `/access/users` | Create a new user account |
| POST | `/access/users/{userid}/token/{token-name}` | Create an API token for a user |
| PUT | `/access/acl` | Set access control list entries |
| GET | `/access/permissions` | Query effective permissions |
| POST | `/access/ticket` | Create an authentication ticket |
| GET | `/admin/datastore/{store}/active-operations` | List active datastore operations |

## Key resources

- **Users** — Create, list, update, and delete user accounts on the backup server
- **Tokens** — Generate, list, and revoke API tokens for user automation
- **ACLs** — Manage path-based access control list entries
- **TFA** — Configure and manage two-factor authentication methods
- **Domains** — List and synchronize authentication realms (PAM, LDAP, OpenID)
- **Permissions** — Query effective permissions for users and tokens

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 76 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/pbs.proxmox.com/pbs-proxmox/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Proxmox Backup Server API by hand means acquiring an authentication ticket via POST `/access/ticket`, carrying the PBSAuthCookie, and adding a CSRFPreventionToken header to every state-changing request against your own {host}:8007 instance yourself. Through Jentic you install once, import Proxmox Backup Server from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Proxmox Backup Server puts the datastore in the URL path (`/admin/datastore/{store}/...`) and the user in `/access/users/{userid}/...`, so a rule can pin your agent to one datastore or user: it can read that store's active operations and nothing else. You choose the operations it may call, so writes like creating users or updating the ACL are not included unless you add them.
- **Credential handling:** Your Proxmox Backup Server credentials are stored once, encrypted, by your own Jentic One instance, which acquires the ticket and injects the cookie and CSRF token at execution time. The raw password never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'manage backup server users' or 'check a datastore's active operations', and Jentic returns the matching Proxmox Backup Server operation with its input schema so the agent calls the right endpoint against the configured instance without reading the reference docs.

## Related APIs

- **Proxmox VE API** — Virtual environment management that creates the VMs being backed up by PBS
- **OpenObserve API** — Observability platform for monitoring backup job metrics and alerts
- **Stripe API** — Payment processing for billing customers using managed backup services

## FAQ

### What authentication does the Proxmox Backup Server API use?

The PBS API uses cookie-based authentication via PBSAuthCookie with a CSRFPreventionToken header for state-changing requests. You obtain a ticket via POST `/access/ticket` with username and password. Alternatively, API tokens provide stateless authentication. Through Jentic, session management and CSRF tokens are handled automatically.

### Can I create API tokens for automated backup jobs?

Yes. POST `/access/users/{userid}/token/{token-name}` creates a token scoped to that user's permissions. Tokens can be used directly in API calls without session management. You can list all tokens via GET `/access/users/{userid}/token` and revoke individual tokens via DELETE.

### What are the rate limits for the Proxmox Backup Server API?

PBS does not impose explicit per-endpoint rate limits as it is a self-hosted solution. Performance depends on your server resources. However, authentication ticket creation (POST `/access/ticket`) applies a per-IP throttle to prevent brute-force attacks.

### How do I manage user permissions through Jentic?

Search Jentic for 'set Proxmox backup permissions', load the schema for PUT `/access/acl`, and execute with the path, user, and role. Jentic handles the cookie authentication and CSRF token injection automatically, returning the updated ACL configuration.

### Does the PBS API support OpenID Connect authentication?

Yes. The API provides POST `/access/openid/auth-url` to generate an OpenID authentication URL and POST `/access/openid/login` to complete the login flow. This enables SSO integration with identity providers like Azure AD, Keycloak, and Google Workspace.

### Can I limit what my agent is allowed to do with the Proxmox Backup Server API?

Yes. You run Jentic One yourself, and your own rules decide which Proxmox Backup Server operations and credentials your agent may use. Because this API puts the datastore in the URL path (`/admin/datastore/{store}/...`) and the user in `/access/users/{userid}/...`, you can pin the agent to a single datastore or user so it only reads that store's active operations. State-changing calls such as creating users via POST `/access/users` or updating the access control list via PUT `/access/acl` stay off limits unless you explicitly grant them.