Schema Management APIs

Admin APIs for managing JSON schemas used to validate principal and resource attributes in Cerbos policies.

The Schema Management APIs allow administrators to manage JSON schemas that validate principal and resource attributes. All endpoints require BasicAuth authentication.

AddOrUpdateSchema

Add or update one or more JSON schemas in the schema store.

HTTP Request

POST /admin/schema
PUT /admin/schema

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Request Body

schemas · array · required

Array of schema objects to add or update. Minimum 1, maximum 100 schemas.

Show Schema Object

id · string · required

Unique identifier for the schema. Maximum 255 characters.

Example: principal.json

definition · bytes · required

JSON schema definition as bytes. Minimum 10 bytes.

Example: {"type":"object", "properties":{"department":{"type":"string"}}}

Response

Returns an empty response object on success.

Example Request

curl -X POST https://cerbos.example.com/admin/schema \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": [
      {
        "id": "principal.json",
        "definition": {
          "type": "object",
          "properties": {
            "department": {"type": "string"},
            "role": {"type": "string"},
            "level": {"type": "number"}
          },
          "required": ["department"]
        }
      }
    ]
  }'

---

ListSchemas

List all schema IDs stored in the Cerbos server.

HTTP Request

GET /admin/schemas

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Response

schemaIds · array

Array of schema ID strings

Example Request

curl https://cerbos.example.com/admin/schemas \
  -u admin:password

Example Response

{
  "schemaIds": [
    "principal.json",
    "resource.album.json",
    "resource.photo.json"
  ]
}

---

GetSchema

Retrieve one or more schemas by their IDs.

HTTP Request

GET /admin/schema

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Query Parameters

id · array · required

One or more schema IDs to retrieve. Minimum 1 ID required. Each ID must be between 1 and 255 characters.

Example: principal.json

Response

schemas · array

Array of schema objects matching the requested IDs

Show Schema Object

id · string

Unique identifier for the schema

definition · bytes

JSON schema definition

Example Request

curl "https://cerbos.example.com/admin/schema?id=principal.json" \
  -u admin:password

Example Response

{
  "schemas": [
    {
      "id": "principal.json",
      "definition": {
        "type": "object",
        "properties": {
          "department": {"type": "string"},
          "role": {"type": "string"},
          "level": {"type": "number"}
        },
        "required": ["department"]
      }
    }
  ]
}

---

DeleteSchema

Permanently delete one or more schemas from the schema store.

HTTP Request

DELETE /admin/schema

Authentication

Requires BasicAuth credentials configured in the Cerbos server.

Query Parameters

id · array · required

One or more schema IDs to delete. Minimum 1 ID required. Each ID must be between 1 and 255 characters.

Example: principal.json

Response

deletedSchemas · number

Number of schemas successfully deleted

Example Request

curl -X DELETE "https://cerbos.example.com/admin/schema?id=principal.json" \
  -u admin:password

Example Response

{
  "deletedSchemas": 1
}