> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pharen.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Pharen Hub API keys: create, scope, and rotate

> Create, scope, store, rotate, and revoke Pharen Hub API keys for programmatic access from scripts, internal tools, and backend services.

API keys let trusted scripts, internal tools, and backend services call Pharen Hub without an interactive login. Create keys for specific automation jobs, give each key only the access it needs, and rotate them when ownership or risk changes.

<Warning>
  Treat API keys like passwords. Do not commit them to source control, paste them into client-side code, or log them in application output.
</Warning>

## Create a key

You create API keys in Pharen Hub.

<Steps>
  <Step title="Open API key settings">
    Go to **Settings → API Keys** in your workspace.
  </Step>

  <Step title="Name the key">
    Choose a short, specific name such as `calendar-sync-production` or `docs-import-worker`.
  </Step>

  <Step title="Choose the access target">
    Select **Entire workspace** for workspace-wide automation, or **Selected teams** when the integration should only work inside specific teams.
  </Step>

  <Step title="Select scopes">
    Choose the minimum permissions the integration needs. You can grant access to lists, docs, calendar, workflows, and agents separately.
  </Step>

  <Step title="Copy the key once">
    Copy the generated key immediately. Pharen only shows the full key once.
  </Step>
</Steps>

## Try API key requests

The endpoint pages in this reference use Mintlify's interactive playground. Add your key as a Bearer token, fill the parameters, and run a request directly from the docs.

In **Try it**, paste the key into **Authorization**. The playground defaults **baseUrl** to `https://pharen.app`. To test a local backend, replace that value with `http://localhost:8000`.

<CardGroup cols={2}>
  <Card title="List calendar events" icon="calendar" href="/api-reference/calendar/list-events">
    Test a `calendar:read` key against a read-only endpoint.
  </Card>

  <Card title="Run workflow" icon="workflow" href="/api-reference/workflows/run-workflow">
    Test a `workflows:run` key against an execution endpoint.
  </Card>

  <Card title="List documents" icon="file-text" href="/api-reference/docs/list-documents">
    Test a `docs:read` key against Pharen Docs.
  </Card>

  <Card title="Chat with agent" icon="bot" href="/api-reference/agents/chat-agent">
    Test an `agents:run` key against an agent chat endpoint.
  </Card>
</CardGroup>

## Use a key

Send the key with every request. Bearer authentication is recommended:

```bash theme={null}
curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "Authorization: Bearer $PHAREN_API_KEY" \
  --header "Content-Type: application/json"
```

You can also use the `X-API-Key` header for server-to-server tools that cannot set an `Authorization` header:

```bash theme={null}
curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "X-API-Key: $PHAREN_API_KEY"
```

<Info>
  API keys generated by Pharen start with `phk_`. Store the full value in a secrets manager or an environment variable such as `PHAREN_API_KEY`.
</Info>

## Permission levels

Lists, Docs, and Calendar use four permission levels.

| Level       | Included scopes                                                          | Use this for                                                 |
| ----------- | ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| None        | No scopes                                                                | Keys that should not access the resource.                    |
| Read        | `resource:read`                                                          | Reports, sync jobs, exports, and read-only dashboards.       |
| Write       | `resource:read`, `resource:create`, `resource:update`                    | Importers and two-way sync jobs that should not delete data. |
| Full access | `resource:read`, `resource:create`, `resource:update`, `resource:delete` | Administrative jobs that are allowed to remove data.         |

Workflows and Agents use focused run permissions.

| Resource  | Read             | Run                               |
| --------- | ---------------- | --------------------------------- |
| Workflows | `workflows:read` | `workflows:read`, `workflows:run` |
| Agents    | `agents:read`    | `agents:read`, `agents:run`       |

## Scope reference

| Scope             | Allows                                                                            |
| ----------------- | --------------------------------------------------------------------------------- |
| `lists:read`      | List saved list data, fields, rows, cells, and views.                             |
| `lists:create`    | Create new lists.                                                                 |
| `lists:update`    | Update lists, fields, rows, cells, views, and sharing metadata.                   |
| `lists:delete`    | Delete lists or list records.                                                     |
| `docs:read`       | Read documents, collections, versions, files, and access metadata.                |
| `docs:create`     | Create documents and collections.                                                 |
| `docs:update`     | Update documents, collections, files, shares, versions, and activity links.       |
| `docs:delete`     | Delete or restore deleted documents and collections.                              |
| `calendar:read`   | Read calendar sources, events, and exports.                                       |
| `calendar:create` | Create calendar sources, events, and imports.                                     |
| `calendar:update` | Update calendar sources and events.                                               |
| `calendar:delete` | Delete calendar sources and events.                                               |
| `workflows:read`  | Read workflow definitions, versions, validation results, and execution plans.     |
| `workflows:run`   | Execute workflows. Streaming execution also requires streaming access on the key. |
| `agents:read`     | Read agents, catalog data, tools, conversations, and logs.                        |
| `agents:run`      | Send agent chat requests or cancel active agent runs.                             |

<Note>
  A key can only do what both the key scopes and the creator's account permissions allow. If the creator loses access, their keys lose that access too.
</Note>

## Workspace and team scope

Every key belongs to one workspace. A workspace-wide key can operate anywhere its scopes and creator permissions allow inside that workspace.

Team-scoped keys are stricter. They only match requests that target one of the selected teams. Use team scope for production automations owned by a single team or department.

## Expiration and rotation

An expiration date is optional, but recommended for temporary jobs and vendor integrations. For long-running production jobs, rotate keys periodically.

1. Create a replacement key with the same or narrower scopes.
2. Deploy the new key to your secrets manager.
3. Confirm the integration works with the new key.
4. Revoke the old key in **Settings → API Keys**.

## Common errors

| Status             | Meaning                                                         | What to do                                                                     |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `401 Unauthorized` | The key is missing, malformed, expired, revoked, or invalid.    | Check the header, secret value, and key status.                                |
| `403 Forbidden`    | The key is valid but lacks the required scope or target access. | Grant the missing scope, choose the right team target, or use a different key. |
| `404 Not Found`    | The target resource is not visible to the key creator.          | Confirm the resource exists and the creator still has access.                  |

## Best practices

* Create one key per integration or environment.
* Name keys by job and environment, not by person.
* Prefer **Read** or **Write** over **Full access** unless deletion is required.
* Use team scope when an automation belongs to one team.
* Store keys in a secrets manager.
* Revoke unused keys immediately.