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.
Authorization: Bearer pf_YOUR_API_KEYYou can send it in the X-API-Key header instead.
X-API-Key: pf_YOUR_API_KEYA 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 "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.
curl https://projectfeed.app/api/v1/auth/check \
-H "Authorization: Bearer pf_YOUR_API_KEY" \
-H "X-Project-Feed-Workspace: your-workspace"authenticated and statusAlways true and active in a successful response. A credential that fails the check returns an error instead.
user IdThe ID of the user the credential acts as. Compare it with author, creator, and assignee IDs to recognize your own writes and assignments.
token IdThe ID of the key or token that made the request.
token Name, created At, last Used AtThe 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.
credential Scopeworkspace for a workspace API key, account for a personal API token. scope repeats the same value.
effective ScopesThe scopes you can use after the credential, your role, and workspace policy are applied.
workspaceThe 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.
audience ModeFor personal API tokens: identity_only, selected_workspaces, or all_workspaces. Null for workspace API keys.
project RestrictionThe 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.
expires AtWhen the credential expires, or null when it does not expire.
installed ToolThe client ID, device name, and provider when the token belongs to a connected installed tool. Otherwise null.
principalOnly returned for installed tool credentials. The signed-in user's id, uploadActorId, and email.
api VersionThe 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.
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.
- Errors lists the response format and every status code.
- Credential security covers rotating and revoking workspace API keys.