API Changelog version 2.33.0

This document describes all Tenant-related API endpoints of the Patrowl Dashboard. It covers tenant information, resource capacity (EASM credits, pentest slots, greybox credits, retest credits), managing the organizations under a tenant, allocating resources to those organizations, and managing the users linked to a tenant.

Base URL:

https://dashboard.cloud.patrowl.io/api/auth/

Authentication: All requests require an API token in the

Authorization

header:

Authorization: Token <your-API-token>

​

A Tenant represents your MSSP or customer account. It holds a pool of resource capacity — EASM credits, pentest slots, greybox credits, and retest credits — that you distribute across one or more Organizations it manages (for example, one organization per customer or business unit).

A tenant can manage multiple organizations.

Each resource type has three figures at any level: capacity (the total available), allocated (the portion assigned to organizations), and used (what has actually been consumed).

Every endpoint in this document requires Tenant Administrator access:

You must be registered as an administrator of the specific tenant you are calling.

Requesting a tenant you do not administer returns

404 Not Found

.

Being an administrator of your own organization does not by itself grant tenant administrator access — it must be explicitly granted (see §5.2).

The tenant list endpoint (

GET /api/auth/tenants/

) only returns tenants you administer.

Returns a paginated list of the tenants you administer.

Example request

GET /api/auth/tenants/ Authorization: Token <your-API-token> Accept: application/json

​

Example response

200 OK

{ "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "name": "Acme MSSP", "brand_image": "iVBORw0KGgoAAAANSUhEUgAA...", "updated_at": "2025-02-20T10:00:00Z", "resources": { "easm_credits": { "capacity": 500, "allocated": 350, "used": 5 }, "pentest_slots": { "capacity": 10, "allocated": 3, "used": 1 }, "greybox_credits": { "capacity": 20, "allocated": 5, "used": 0 }, "retest_credits": { "capacity": 20, "allocated": 5, "used": 0 } } } ] }

​

brand_image

is your tenant logo, encoded as a base64 string (or

null

if none is set).

Possible status codes

URL parameters

Example request

GET /api/auth/tenants/1/ Authorization: Token <your-API-token> Accept: application/json

​

Example response

200 OK

Same shape as a single item of §1.1's

results

.

Possible status codes

Add or remove users from organizations in bulk, within a tenant.

Adds every user in

user_ids

to every organization in

organization_ids

. Users already members of an organization are left unchanged.

URL parameters

Request body (JSON)

Example request

POST /api/auth/tenants/1/memberships/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "user_ids": [10, 11], "organization_ids": [5, 6] }

​

Example response

200 OK

{ "status": "created" }

​

Possible status codes

Removes every user in

user_ids

from every organization in

organization_ids

. Removing a user from an organization also clears anything they own or are assigned to within that organization (assets, asset groups, vulnerabilities, remediations, team memberships, and pending notifications).

URL parameters

Request body (JSON)

Example request

DELETE /api/auth/tenants/1/memberships/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "user_ids": [10, 11], "organization_ids": [5, 6] }

​

Example response

200 OK

{ "status": "success" }

​

Possible status codes

Manage the organizations your tenant provisions and owns.

URL parameters

Query parameters

Example request

GET /api/auth/tenants/1/organizations/?search=acme Authorization: Token <your-API-token> Accept: application/json

​

Example response

200 OK

{ "count": 1, "next": null, "previous": null, "results": [ { "id": 5, "name": "Acme UK", "member_total": 3, "member_preview": [ { "id": 10, "email": "[email protected]" }, { "id": 11, "email": "[email protected]" } ], "created_by": "[email protected]", "created_at": "2025-01-10T09:00:00Z", "updated_at": "2025-02-20T10:00:00Z" } ] }

​

member_preview

lists up to 5 members of the organization.

created_by

may be

null

if unknown.

Possible status codes

Creates a new organization managed by the tenant, with an optional logo and initial resource allocations (each defaults to

0

).

URL parameters

Request body (JSON)

Requested allocations cannot exceed the tenant's remaining (unallocated) capacity for each resource.

Example request

POST /api/auth/tenants/1/organizations/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "name": "Acme UK", "easm_credits": 50, "pentest_slots": 2, "greybox_credits": 5, "retest_credits": 5 }

​

Example response

201 Created

{ "id": 5, "name": "Acme UK", "resources": { "easm_credits": { "capacity": 500, "allocated": 50, "used": 0 }, "pentest_slots": { "capacity": 10, "allocated": 2, "used": 0 }, "greybox_credits": { "capacity": 20, "allocated": 5, "used": 0 }, "retest_credits": { "capacity": 20, "allocated": 5, "used": 0 } }, "created_by": "[email protected]", "created_at": "2025-02-20T10:00:00Z", "updated_at": "2025-02-20T10:00:00Z" }

​

Possible status codes

URL parameters

Request body (JSON)

Example request

PATCH /api/auth/tenants/1/organizations/5/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "name": "Acme UK Ltd" }

​

Example response

200 OK

{ "id": 5, "name": "Acme UK Ltd", "updated_at": "2025-02-21T08:00:00Z" }

​

Possible status codes

Deletes one or more organizations of a tenant. Their resource allocations are released back to the tenant's available capacity.

URL parameters

Request body (JSON)

Example request

DELETE /api/auth/tenants/1/organizations/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "ids": [5, 6] }

​

Example response

200 OK

{ "deleted_ids": [5, 6] }

​

Example error response

400 Bad Request

(some ids outside the tenant)

{ "invalid_ids": [99] }

​

Possible status codes

View and adjust how much of the tenant's resource capacity is allocated to each organization.

URL parameters

Query parameters

Example request

GET /api/auth/tenants/1/organizations/resources/?search=acme Authorization: Token <your-API-token> Accept: application/json

​

Example response

200 OK

{ "count": 1, "next": null, "previous": null, "results": [ { "id": 5, "name": "Acme UK", "asset_count": 42, "resources": { "easm_credits": { "capacity": 500, "allocated": 50, "used": 42 }, "pentest_slots": { "capacity": 10, "allocated": 2, "used": 1 }, "greybox_credits": { "capacity": 20, "allocated": 5, "used": 0 }, "retest_credits": { "capacity": 20, "allocated": 5, "used": 0 } }, "created_at": "2025-01-10T09:00:00Z", "updated_at": "2025-02-20T10:00:00Z" } ] }

​

asset_count

is the number of active assets monitored for that organization.

Possible status codes

Updates one or more of the organization's allocations (EASM credits, pentest slots, greybox credits, retest credits). At least one field is required.

URL parameters

Request body (JSON)

A new value cannot be set below what the organization is already using, and cannot exceed the tenant's remaining available capacity.

Example request

PATCH /api/auth/tenants/1/organizations/5/resources/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "easm_credits": 100 }

​

Example response

200 OK

{ "resources": { "easm_credits": { "capacity": 500, "allocated": 100, "used": 42 }, "pentest_slots": { "capacity": 10, "allocated": 2, "used": 1 }, "greybox_credits": { "capacity": 20, "allocated": 5, "used": 0 }, "retest_credits": { "capacity": 20, "allocated": 5, "used": 0 } } }

​

Example error response

400 Bad Request

{ "easm_credits": "Cannot set easm_credits to 10: 42 are currently in use for this organization." }

​

or, when exceeding the tenant's remaining capacity:

{ "easm_credits": "Cannot set easm_credits to 600: tenant capacity allows 450 at most (500 total, 50 allocated to other organizations)." }

​

Possible status codes

Directory of the users linked to a tenant, plus tenant-administrator management and CSV export.

Returns users linked to the tenant directly, or through membership in one of its organizations.

URL parameters

Query parameters

Example request

GET /api/auth/tenants/1/users/?search=org_member@customer Authorization: Token <your-API-token> Accept: application/json

​

Example response

200 OK

{ "count": 1, "next": null, "previous": null, "results": [ { "id": 11, "email": "[email protected]", "first_name": "Org", "last_name": "Member", "is_active": true, "is_tenant_admin": false, "last_login": "2025-02-19T07:30:00Z", "organizations": [{ "id": 5, "name": "Acme UK", "slug": "acme-uk" }] } ] }

​

organizations

only lists organizations belonging to this tenant.

Possible status codes

Grants tenant-administrator access to an existing user.

URL parameters

Request body (JSON)

Example request

POST /api/auth/tenants/1/users/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "user_id": 12 }

​

Example response

201 Created

{ "user_id": 12, "tenant_id": 1 }

​

Possible status codes

Demotes a tenant administrator back to a standard tenant member. At least one administrator must always remain.

URL parameters

Request body (JSON)

Example request

DELETE /api/auth/tenants/1/users/ Authorization: Token <your-API-token> Content-Type: application/json Accept: application/json { "user_id": 12 }

​

Example response

200 OK

{ "user_id": 12 }

​

Possible status codes

Exports users linked to the tenant as a CSV file.

GET

exports according to the same filters as §5.1;

POST

exports only the given user ids.

URL parameters

GET Applies the same query parameters as §5.1. No body.

POST

Request body (JSON)

Example request (GET)

GET /api/auth/tenants/1/users/export/?is_active=true Authorization: Token <your-API-token> Accept: text/csv

​

Example request (POST)

POST /api/auth/tenants/1/users/export/ Authorization: Token <your-API-token> Content-Type: application/json Accept: text/csv { "users_id": [10, 11] }

​

Response

200 OK

Content-Type:

text/csv

Content-Disposition:

attachment; filename="users_YYYY-MM-DD_HH-MM-SS.csv"

.

CSV columns (in order):

Email

,

Firstname

,

Lastname

,

Enabled

,

Role

,

Last login

,

Organizations

(comma-separated list of the tenant's organizations the user belongs to).

A JSON response can be requested instead of CSV by sending

Accept: application/json

.

Possible status codes

Errors are generally returned as a JSON body describing what went wrong, either as a general message:

{ "detail": "Human-readable description of the error." }

​

or as a field-specific message:

{ "<field_name>": "Human-readable description of the error." }

​

HTTP status codes used across this document: