Tenant API

The Tenant API lets you create tenants (workspaces), retrieve tenant details, and rotate API keys. Each tenant is an isolated workspace with its own keys, quotas, and billing plan.

---

Create Tenant

POST/api/v1/tenantsCreate a new tenant workspace and receive an API key.

Creates a new tenant with the specified name and plan. Returns the tenant details along with an API key.

⚠️API key shown once

The api_key field is included only in the creation response. It is never returned again. Copy it immediately and store it in a secure location such as a secrets manager or encrypted vault.

Request body

Field	Type	Required	Description
name	string	Yes	A human-readable name for the tenant (2-100 characters).
plan	string	Yes	Pricing plan: "free", "starter", "growth", "pro", or "enterprise".

Response (200 OK)

Field	Type	Description
data.id	string (UUID)	The unique tenant identifier.
data.name	string	The tenant name.
data.plan	string	The selected plan.
data.status	string	Tenant status, initially "active".
data.api_key	string	The API key. Shown only once.
data.created_at	string (ISO 8601)	When the tenant was created.

Example

RequestPOST/api/v1/tenants

Content-Type: application/json

{
  "name": "Acme Corp",
  "plan": "starter"
}

Response200

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Acme Corp",
    "plan": "starter",
    "status": "active",
    "api_key": "qph_your_key_here",
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "request_id": "d0e1f2a3-b4c5-6789-0123-456789abcdef",
  "timestamp": "2026-01-15T10:00:00.000Z"
}

Create tenant

curl -X POST https://api.qpher.ai/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "plan": "starter"
  }'

Errors

HTTP Status	Error Code	Description
400	ERR_INVALID_001	Invalid request body — missing name, invalid plan, or name too short/long.
409	ERR_CONFLICT_001	A tenant with this name already exists.

---

Get Tenant

GET/api/v1/tenants/{id}Retrieve details for a specific tenant.

Returns tenant details. The API key is not included in this response for security reasons.

Path parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	The tenant ID.

Response (200 OK)

Field	Type	Description
data.id	string (UUID)	The tenant identifier.
data.name	string	The tenant name.
data.plan	string	The current plan.
data.status	string	Tenant status: "active", "suspended", etc.
data.created_at	string (ISO 8601)	When the tenant was created.
data.updated_at	string (ISO 8601)	When the tenant was last updated.

Example

RequestGET/api/v1/tenants/f47ac10b-58cc-4372-a567-0e02b2c3d479

X-API-Key: qph_your_key_here

Response200

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Acme Corp",
    "plan": "starter",
    "status": "active",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z"
  },
  "request_id": "e1f2a3b4-c5d6-7890-1234-567890abcdef",
  "timestamp": "2026-01-15T10:05:00.000Z"
}

Get tenant

curl -X GET https://api.qpher.ai/api/v1/tenants/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: qph_your_key_here"

Errors

HTTP Status	Error Code	Description
401	ERR_AUTH_001	Missing or invalid API key.
404	ERR_NOT_FOUND_001	Tenant not found.

---

Rotate API Key

POST/api/v1/tenants/{id}/api-keys/rotateRotate the API key for a tenant, revoking the old key.

Generates a new API key and immediately revokes the old one. There is a brief concurrent window where both keys are valid to allow for zero-downtime rotation.

⚠️API key shown once

The new api_key is included only in this response. Store it immediately. The old key will stop working shortly after rotation.

Path parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	The tenant ID.

Response (200 OK)

Field	Type	Description
data.api_key	string	The new API key. Shown only once.
data.api_key_version	integer	The version number of the new key.
data.previous_key_revoked	boolean	Whether the old key was revoked.

Example

RequestPOST/api/v1/tenants/f47ac10b-58cc-4372-a567-0e02b2c3d479/api-keys/rotate

X-API-Key: qph_your_key_here
Content-Type: application/json

Response200

{
  "data": {
    "api_key": "qph_new_rotated_key_here",
    "api_key_version": 2,
    "previous_key_revoked": true
  },
  "request_id": "f2a3b4c5-d6e7-8901-2345-678901abcdef",
  "timestamp": "2026-02-01T12:00:00.000Z"
}

Rotate API key

curl -X POST https://api.qpher.ai/api/v1/tenants/f47ac10b-58cc-4372-a567-0e02b2c3d479/api-keys/rotate \
  -H "X-API-Key: qph_your_key_here" \
  -H "Content-Type: application/json"

Errors

HTTP Status	Error Code	Description
401	ERR_AUTH_001	Missing or invalid API key.
404	ERR_NOT_FOUND_001	Tenant not found.

---

Plan Tiers

Plan	Monthly Price	Requests/min	PQC Keys
Free	$0	100	2
Starter	$99	500	10
Growth	$179	1,000	25
Pro	$299	5,000	100
Enterprise	From $999	Custom	Unlimited

💡Upgrading your plan

To change your plan, use the Qpher Portal at portal.qpher.ai or contact sales for Enterprise pricing.