---
title: "Workspace access API reference"
canonical_url: https://zentrik.ai/docs/api/auth
markdown_url: https://zentrik.ai/docs/api/auth.md
last_reviewed: 2026-09-13
---

# Workspace access API reference

Verify existing REST access or provision a prospect workspace with a separate administrative credential. Creation uses the normal workspace lifecycle and needs no browser session.

- Human reference: https://zentrik.ai/docs/api/auth
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/auth/context — Read credential context

Operation ID: `get-auth-context`

Read the exact workspace, credential ID, scopes and expiry selected by this REST key. Works in an empty workspace without creating probe records. Returns no secret or hash. No additional resource scope is required.



### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Workspace identity and credential metadata, without the secret. | — |
| 401 | Invalid credential | The key is invalid, expired or revoked. | — |

---

## POST /external/v1/workspaces — Provision a prospect workspace

Operation ID: `provision-workspace`

Create a real prospect evaluation workspace with its normal Owner, default team, trial plan and full content API key. Requires a separate provisioning-only key with workspaces:provision, issued by an eligible Zentrik administrator in Settings > API Keys. Normal content keys cannot call this route. The content key has its own expiry and remains usable after the provisioning credential expires or is revoked. Repeating the same owner/reference reuses the workspace, preserves its name and plan, and replaces only the last key issued by this endpoint. Save the one-time secret and use auth/context for normal resumes; repeated POSTs rotate that key. Different references run independently.

Required API key scopes: `workspaces:provision`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | Yes | Stable prospect reference, unique per owning user and environment. 1-120 lowercase letters, digits, dots, underscores, colons or hyphens; first character is a letter or digit. Never change it to retry. |
| `name` | string | Yes | Initial workspace name, 1-80 characters without control characters. Ignored on retry; existing names are preserved. |
| `keyName` | string | No | Normal workspace key name, 1-80 characters. Default: a name like `Zentrik Setup [agent-912]`, using the server’s UTC month and day. |
| `keyExpiresAt` | ISO timestamp | No | Future workspace key expiry. Default: 90 days from this request. Does not extend the existing 14-day workspace trial. |
| `expectedWorkspaceId` | UUID | No | For explicit replacement: require this reference to already identify this workspace. Refuses a different owner or destination without creating anything. |

### Example request

```json
{
  "reference": "calendly",
  "name": "Calendly Sandbox",
  "keyName": "Zentrik Setup [agent-912]"
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | reference, workspace {id,name}, key {id,name,keyPrefix,scopes,expiresAt,secret}, plan {tier,status,subscriptionEnd}, and replayed. Store secret privately; response is private, no-store. | — |
| 400 | Invalid input | Invalid reference, name, future expiry or unexpected field. | — |
| 401 | Invalid credential | The provisioning key is invalid, expired or revoked. | — |
| 403 | Not authorized | Missing provisioning-only scope, inactive/non-administrator creator, or lost Owner membership. | — |
| 409 | Workspace unavailable | Expected workspace does not match, or the destination is being deleted. | — |
| 410 | Workspace removed | This reference previously created a workspace which was deleted. It will not be recreated. | — |