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

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.

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

Create a key

You create API keys in Pharen Hub.

Open API key settings

Go to Settings → API Keys in your workspace.

Name the key

Choose a short, specific name such as calendar-sync-production or docs-import-worker.

Choose the access target

Select Entire workspace for workspace-wide automation, or Selected teams when the integration should only work inside specific teams.

Select scopes

Choose the minimum permissions the integration needs. You can grant access to lists, docs, calendar, workflows, and agents separately.

Copy the key once

Copy the generated key immediately. Pharen only shows the full key once.

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.

List calendar events

Test a calendar:read key against a read-only endpoint.

Run workflow

Test a workflows:run key against an execution endpoint.

List documents

Test a docs:read key against Pharen Docs.

Chat with agent

Test an agents:run key against an agent chat endpoint.

Use a key

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

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:

curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "X-API-Key: $PHAREN_API_KEY"

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.

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.

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.

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.

Create a replacement key with the same or narrower scopes.
Deploy the new key to your secrets manager.
Confirm the integration works with the new key.
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.

​Create a key

​Try API key requests

List calendar events

Run workflow

List documents

Chat with agent

​Use a key

​Permission levels

​Scope reference

​Workspace and team scope

​Expiration and rotation

​Common errors

​Best practices

Create a key

Try API key requests

Use a key

Permission levels

Scope reference

Workspace and team scope

Expiration and rotation

Common errors

Best practices