Skip to main content
Use this endpoint to generate a new Open API key with one or more permission scopes and an optional expiry date. After creation, the full plaintext key is shown exactly once — copy it immediately into a secure secrets manager.
This endpoint uses session cookie authentication (plangrep_session). It is used by the Plangrep app’s API settings page and does not accept a bearer API key.

​
Endpoint

POST https://plangrep.com/api/open-api/keys

​
Authentication

MethodValue
Cookieplangrep_session=YOUR_SESSION_COOKIE

​
Request Body

​
label
string
required
A human-readable name for the key (e.g., "CI Pipeline" or "Acme Corp Integration"). Maximum 120 characters.
​
scopes
OpenApiKeyScope[]
required
One or more permission scopes to grant this key. At least one scope is required.
ScopeAccess Granted
jobs:readRead job state and results
jobs:writeCreate jobs, upload files, complete uploads, resume and cancel jobs
artifacts:readFetch authenticated artifact download URLs
​
expiresAt
string
Optional expiration timestamp in ISO 8601 format (e.g., "2025-12-31T23:59:59Z"). Must be a future date. If omitted, the key never expires.

​
Response

201 Created Returns an OpenApiKeyCreateResponse object.
​
key
OpenApiKey
required
Metadata for the newly created key.
​
plaintextKey
string
required
The full plaintext key to use in API requests. This value is shown exactly once and is not stored by Plangrep. Copy it immediately and store it in a secure secrets manager.
Save your key before navigating away. The plaintextKey is returned only on this response. Plangrep stores only a secure hash and cannot recover or redisplay the full key. If you lose it, you must revoke the key and create a new one.

​
Scope Reference

ScopeAccess Granted
jobs:readRead job state, status, and results
jobs:writeCreate jobs, upload files, complete uploads, resume and cancel jobs
artifacts:readFetch authenticated artifact download URLs
Follow the principle of least privilege — only grant the scopes your integration actually needs. For a read-only reporting integration, jobs:read alone is sufficient.

​
Example

curl -X POST https://plangrep.com/api/open-api/keys \
  -H "Cookie: plangrep_session=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Integration Key",
    "scopes": ["jobs:read", "jobs:write", "artifacts:read"]
  }'

​
Example Response

{
  "key": {
    "id": "key_01hx3z...",
    "label": "My Integration Key",
    "keyPrefix": "pgk_live_abc1",
    "scopes": ["jobs:read", "jobs:write", "artifacts:read"],
    "createdByUserId": "usr_01hx3y...",
    "hashVersion": "v1",
    "createdAt": "2025-01-20T14:30:00Z",
    "expiresAt": null,
    "lastUsedAt": null,
    "lastUsedIp": null,
    "revokedAt": null
  },
  "plaintextKey": "pgk_live_abc1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
The plaintextKey in the response above is your only opportunity to copy this value. It will not appear again.