Generate an API key
Create a scoped API key, bind it to a pipeline, copy the one-time secret, and rotate or revoke it later without breaking the callers that use it.
An API key authenticates programmatic calls to IDPForge with the X-API-Key header, and binds the pipeline those calls run against.
Workspace admins. Creating, scoping, and revoking keys is an admin action; a developer can then use the key from code.
The API keys console. The workspace organization key sits at the top with full access; issued keys are listed below with their scopes, bound pipelines, and status.
1. Open the API keys console
In Settings → API Keys you will find the workspace's keys. The banner is a standing reminder: a key grants workspace-level access, so treat it like a password — scope it minimally and rotate it regularly.
2. Create and name the key
Choose Create key and give it a name that says where it runs — production-extract, ci-staging, snowflake-export. The name is how you will recognise the key in the list and in audit events later.
3. Choose scopes
Grant only the scopes the caller needs — for example jobs:write for a job submitter, jobs:read for a status poller, and pipeline:read to list pipelines. A read-only poller needs none of the write scopes.
4. Bind a pipeline
A key runs against a pipeline, so callers do not specify one per request. Bind the key to a single published pipeline, or leave it on all pipelines for a general-purpose key.
5. Copy the one-time secret
The full key — prefixed idpf_live_ in production, idpf_sandbox_ in sandbox — is shown once, at creation. Copy it into your secret store now.
IDPForge stores only a hash of the key, never the key itself. If you lose the secret you cannot recover it — rotate the key to get a new one.
6. Rotate or revoke later
From a key's row you can rotate it — issue a new secret while the old one keeps working through an overlap window, so callers migrate without downtime — or revoke it, which stops it immediately.
Edge cases
- The organization key is rotate-only. Every workspace has one full-access organization key — the workspace's root credential. It can be rotated but not revoked or rescoped.
- Sandbox and production keys are separate. The environment is baked into the key, and a job inherits its environment from the key that submitted it unless you override it. Keep sandbox keys out of production callers.
- Scopes today shape access, not a hard per-scope gate. Scopes drive what a key is listed and searched by and the access model around it; enforcement at call time is tightening over time. Scope minimally regardless.