Skip to content

Authentication

Send a workspace API key or personal API token with every request, and check it before you rely on it.

Send a credential

Put the secret in the Authorization header as a Bearer token.

HTTP
Authorization: Bearer pf_YOUR_API_KEY

You can send it in the X-API-Key header instead.

HTTP
X-API-Key: pf_YOUR_API_KEY

A personal API token also needs the X-Project-Feed-Workspace header on workspace routes. A workspace API key does not. See the workspace header.

curl
curl "https://projectfeed.app/api/v1/projects" \
  -H "Authorization: Bearer $PROJECT_FEED_API_KEY"

Read the secret from an environment variable or secret store. Keep it out of browser code and source control, and make requests from a server.

Verify a credential before use

Check a new or rotated secret before you connect it to a scheduled job. The check needs no scope, and both credential types can call it. Send the workspace header to check a personal API token against one workspace. Without it, a personal API token is checked as an identity and workspace is null.

Shell
curl https://projectfeed.app/api/v1/auth/check \
  -H "Authorization: Bearer pf_YOUR_API_KEY" \
  -H "X-Project-Feed-Workspace: your-workspace"
authenticated and status

Always true and active in a successful response. A credential that fails the check returns an error instead.

userId

The ID of the user the credential acts as. Compare it with author, creator, and assignee IDs to recognize your own writes and assignments.

tokenId

The ID of the key or token that made the request.

tokenName, createdAt, lastUsedAt

The name the key was given, when it was created, and when it was last used before this request. lastUsedAt is null for a key that was never used, and it is updated at most once every 15 minutes. Times are Unix milliseconds.

credentialScope

workspace for a workspace API key, account for a personal API token. scope repeats the same value.

effectiveScopes

The scopes you can use after the credential, your role, and workspace policy are applied.

workspace

The workspace ID, slug, plan, and your role in it (owner, admin, member, or viewer), or null when a personal API token was checked without a workspace.

audienceMode

For personal API tokens: identity_only, selected_workspaces, or all_workspaces. Null for workspace API keys.

projectRestriction

The restriction version and the token's project IDs in projectIds, or null for a token without a project restriction. Version 1 restrictions list a single projectId.

expiresAt

When the credential expires, or null when it does not expire.

installedTool

The client ID, device name, and provider when the token belongs to a connected installed tool. Otherwise null.

principal

Only returned for installed tool credentials. The signed-in user's id, uploadActorId, and email.

apiVersion

The API major version. defaultDateVersion and supportedVersions list the date versions the API accepts.

Confirm the workspace and scopes in the response, then run one read request against the resource you plan to use. For a credential that writes, change a disposable record and confirm it in Project Feed.

Revoke the credential you are using

A job or script can revoke its own key or token when it no longer needs it, or when it finds the secret exposed. The request needs no scope, and the credential stops working at once. Any later call with it returns 401. OAuth connections cannot be revoked this way. They return 400 and are disconnected from the connected app.

Shell
curl --request DELETE https://projectfeed.app/api/v1/auth/token \
  -H "Authorization: Bearer pf_YOUR_API_KEY"

Credential types

Both types are sent the same way. They differ in who owns them and how they reach a workspace. The scopes page covers permissions, expiry, and plan limits.

Use a personal API token when

  • A script or tool acts as you across several workspaces.
  • You create it under Account, Tools & tokens and choose the workspaces it can reach.

Use something else when

  • Automation belongs to one workspace. Use a workspace API key from service accounts.
  • A workspace policy blocks personal API tokens for that workspace.

Create a workspace API key in Workspace settings, under Developers, Service accounts. On Free the page is called Read-only API keys.

Limit a personal token to specific projects

In Account, Tools & tokens, create a token or choose Duplicate token from an existing token's menu. Duplication copies its permissions into a new token. You can change the workspace and project; the original stays active, and the new token must satisfy any workspace approval policy.

On the Access step, choose Specific and select one workspace, then choose Selected projects and pick up to 25 projects. The limit also applies when you own the workspace. The token can view those projects, list, create, and update their tasks and posts, work with plain-text or Markdown comments, read a post's tags, activity, and reactions, manage task checklists, read a task's activity and tags, log and edit time on its tasks, attach links to tasks and posts, start an external issue from a task, and count a project's tasks, subject to the token's permissions and your current access. If you lose access to one of the projects, the token keeps working in the others.

Project tokens cannot upload files, assign tags, write annotations, delete tasks or posts, or use workspace-wide operations. Time lists and summaries, the timer, saved task views, the tag catalog, and task counts across projects are workspace-wide and stay unavailable. Search, docs, canvas, chat, event subscriptions, handoffs, and MCP resources and prompts are unavailable. Structured editor content is not accepted. Unsupported requests are denied even if the token has the corresponding permission. Rolling a token keeps its projects; duplicate it to choose different ones.

Fix authentication failures

401 Unauthorized

The header is missing or malformed, the secret is wrong, or the credential is expired, revoked, or replaced by a rotation. Run the check above with the new secret before restarting a client.

400 with workspace_required

A personal API token was sent to a workspace route without the X-Project-Feed-Workspace header.

403 with permission_denied

The credential is valid but does not have the scope for this route. Compare effectiveScopes from the check with the scopes on the endpoint.

403 with plan_required

The workspace is on Free, which allows reads on a few resources only. Writes and other resources need Pro or Enterprise.

403 with workspace_access_denied

A personal API token is not allowed for that workspace, or you are no longer a member. Check the token's workspace access under Account, Tools & tokens.

403 with token_age_exceeded

The workspace sets a maximum key age and this key is older. Rotate the key.

400 when revoking a credential

The credential is an OAuth connection, such as an MCP client. Disconnect it from the connected app instead.

A secret was exposed

Revoke or rotate it now, update your secret store, verify the replacement, and review recent activity.

Image preview
100%