Skip to main content
Plangrep uses bearer token authentication for all Open API routes. You create API keys from the Plangrep app’s API settings page and pass them in the Authorization header of every request. Each key carries one or more scopes that limit exactly which actions it can perform.

​
Authentication scheme

Every endpoint under /api/open/v1/... requires a bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Example request 
curl https://plangrep.com/api/open/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"
The Workspace API Keys endpoints (/api/open-api/keys) use cookie/session authentication from the Plangrep app itself. They are not accessible with a bearer API key.

​
Key scopes

When you create an API key, select the minimum set of scopes your integration requires.
ScopeAccess granted
jobs:readRead job state and results
jobs:writeCreate jobs, upload files, complete uploads, resume and cancel jobs
artifacts:readFetch authenticated artifact URLs
Always create keys with the minimum scopes your integration needs. Narrowly scoped keys limit the blast radius if a key is ever leaked or compromised.

​
Creating an API key

1
Sign in to the Plangrep app
2
Go to plangrep.com and sign in to your account.
3
Open API settings
4
Navigate to Settings → API to reach the API keys management page.
5
Create a new key
6
Click Create API key.
7
Configure the key
8
Enter a descriptive label so you can identify the key later. Select the scopes your integration needs. Optionally set an expiration date to auto-expire the key after a fixed period.
9
Copy the plaintext key
10
After creation, copy the plaintextKey value displayed on screen.
11
The plaintext key is shown only once at creation time. Store it securely in a secrets manager or environment variable immediately — you cannot retrieve it again after you close this screen.

​
Key lifecycle

  • Revocation — Revoke individual keys from the API settings page, or revoke all keys at once. Revoked keys are rejected immediately on the next request.
  • Audit fields — Every key records lastUsedAt and lastUsedIp so you can audit usage and detect unexpected access.
  • Expiration — Set expiresAt during creation to auto-expire keys on a schedule. Expired keys behave identically to revoked keys.

​
Error responses

Requests with a missing, invalid, or revoked bearer token receive a 401 Unauthorized response: 
{
  "error": {
    "code": "unauthorized",
    "message": "..."
  }
}
All Plangrep API errors follow the same shape: 
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Check the code field to distinguish error types programmatically — the message field is human-readable and subject to change.