> 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/authentication.md).

# Authentication

Planck AI API requests are authenticated using API keys.

Each API key is tied to a user account and inherits that user’s access permissions. This means the API key can only access the workspaces, documents, conversations, and integrations that the user is allowed to access.

### Getting your API key

To create an API key:

1. Log in to Planck AI
2. Go to **User Settings**
3. Open **API Keys**
4. Enter a name for the key, such as:

```
My Integration
```

5. Click **Create**
6. Copy and store the API key immediately

The full API key is shown only once. If you lose it, you will need to create a new key.

### Using the API key

Include the API key in the request header:

```
X-API-Key: pk_live_your_key_here
```

Example request:

```
curl -H "X-API-Key: pk_live_your_key_here" \  "https://<your-planck-domain>/api/v1/workspaces"
```

Replace:

```
<your-planck-domain>
```

with the actual URL for your Planck AI instance.

### Permissions

API keys inherit the permissions of the user who created them.

For example:

* If the user can access only one workspace, the API key can access only that workspace.
* If the user cannot access a document, the API key cannot access that document.
* If the user is not an admin, the API key cannot call admin-only endpoints.

Admin API endpoints require an API key owned by a user with the **Admin** role.

### Security best practices

Follow these security practices when using API keys:

* Never commit API keys to version control
* Store API keys in environment variables or a secure secrets manager
* Rotate keys periodically
* Delete unused keys
* Use separate keys for different integrations
* Do not share API keys between users
* Give users only the permissions they need

### Environment variable example

Store the API key in an environment variable:

```
export PLANCK_API_KEY="pk_live_your_key_here"
```

Use it in a request:

```
curl -H "X-API-Key: $PLANCK_API_KEY" \  "https://<your-planck-domain>/api/v1/workspaces"
```

### Common authentication errors

| Status code | Meaning                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| `401`       | Missing or invalid API key                                                |
| `403`       | API key is valid, but the user does not have permission for this endpoint |
| `404`       | The requested resource was not found or is not accessible to the user     |

### Example 401 error

A request without a valid API key may return:

```
{  "detail": "Invalid or missing API key"}
```

### Recommended next pages

* **API Overview** — understand the main API areas
* **Chat API** — send stateless chat messages
* **Conversations API** — create and manage multi-turn conversations
* **Admin API** — provision users and issue API keys


---

# 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/authentication.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.