> For the complete documentation index, see [llms.txt](https://planck-ai.gitbook.io/planck-ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://planck-ai.gitbook.io/planck-ai-docs/documentation/reference/admin-api.md).

# Admin API

The Admin API provides a small set of admin-only endpoints for external provisioning workflows.

Use these endpoints when you want to create users, add users to workspaces, and issue API keys programmatically.

### Requirements

Admin API endpoints require:

* A valid API key
* The API key must belong to a user with the **Admin** role
* The endpoint must be allowed for API-key access

A non-admin user calling these endpoints receives a `403 Forbidden` response.

### Available admin endpoints

| Method | Endpoint                                          | Description                          |
| ------ | ------------------------------------------------- | ------------------------------------ |
| `POST` | `/api/v1/admin/users`                             | Create a new user                    |
| `GET`  | `/api/v1/admin/users/by-email?email=...`          | Look up a user by email              |
| `POST` | `/api/v1/admin/workspaces/{workspace_id}/members` | Add one or more users to a workspace |
| `POST` | `/api/v1/admin/users/{user_id}/api-keys`          | Issue an API key for a user          |

### Flow A: Create a new user

Use this flow when the user does not already exist in Planck AI.

#### Step 1: Create the user

```bash
curl -X POST "https://<your-planck-domain>/api/v1/admin/users" \
  -H "X-API-Key: pk_live_admin_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "password": "ChangeMe123!",
    "full_name": "New User",
    "role": "User"
  }'
```

Example response:

```
{  "id": "user-uuid",  "email": "new.user@example.com",  "full_name": "New User",  "role": "User",  "is_active": true}
```

If the email already exists, the server returns `409 Conflict`.

In that case, use the existing user flow instead.

### Step 2: Add the user to a workspace

```
curl -X POST "https://<your-planck-domain>/api/v1/admin/workspaces/WORKSPACE_ID/members" \  -H "X-API-Key: pk_live_admin_key_here" \  -H "Content-Type: application/json" \  -d '[    {      "user_id": "user-uuid",      "role": "viewer"    }  ]'
```

The request accepts an array, so you can add multiple users in one call.

Supported workspace member roles:

* `viewer`
* `editor`

Adding a user who is already a member is idempotent. The call succeeds without duplicating the member.

### Step 3: Generate an API key for the user

```
curl -X POST "https://<your-planck-domain>/api/v1/admin/users/USER_ID/api-keys" \  -H "X-API-Key: pk_live_admin_key_here" \  -H "Content-Type: application/json" \  -d '{    "name": "default-key"  }'
```

Example response:

```
{  "id": "key-uuid",  "name": "default-key",  "key_prefix": "pk_live_abc12345...",  "api_key": "pk_live_abc123456789...",  "is_active": true,  "created_at": "2026-05-08T13:55:00Z",  "last_used_at": null}
```

Important: the full `api_key` value is returned only once.

Store it immediately. It cannot be retrieved later.

### Flow B: Existing user

Use this flow when the user already exists.

#### Step 1: Look up the user by email

```
curl -H "X-API-Key: pk_live_admin_key_here" \  "https://<your-planck-domain>/api/v1/admin/users/by-email?email=existing.user@example.com"
```

The endpoint returns the user object if found.

If no user has that email, it returns `404 Not Found`.

#### Step 2: Add the user to a workspace

Use the same workspace member endpoint:

```
POST /api/v1/admin/workspaces/{workspace_id}/members
```

If the user is already a member, the call succeeds without changes.

#### Step 3: Issue an additional API key

Use the same API key endpoint:

```
POST /api/v1/admin/users/{user_id}/api-keys
```

A user can have multiple active API keys.

### Common admin errors

| Status code | Meaning                                          |
| ----------- | ------------------------------------------------ |
| `400`       | Target user is inactive when issuing a key       |
| `401`       | Missing or invalid API key                       |
| `403`       | API key belongs to a user without the Admin role |
| `404`       | User or workspace not found                      |
| `409`       | Email already exists when creating a user        |

### Security notes

Admin API keys are highly privileged.

Use them carefully.

Recommended practices:

* Store admin API keys in a secure secrets manager
* Never expose admin keys in frontend code
* Rotate admin keys periodically
* Use separate admin keys for separate provisioning systems
* Delete unused keys immediately
* Log and review provisioning activity
* Prefer least-privilege workspace roles for newly added users

### Recommended next pages

* **Authentication** — learn how API keys work
* **Response Format** — understand streamed responses and content blocks
* **Error Handling** — understand common API errors


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://planck-ai.gitbook.io/planck-ai-docs/documentation/reference/admin-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.