API keys & scopes

API keys let scripts, CI pipelines, the CLI and MCP clients call the ERP Preflight API without an interactive sign-in. A key belongs to exactly one organization and only reaches the routes its scopes allow; every other route is denied.

• Only organization owners and security admins can create, list and revoke keys, and only while signed in interactively — an API key can never manage API keys.
• Creating a key requires a verified e-mail address.
• Creating and revoking a key is recorded in the audit log (api_key.created, api_key.revoked).

In the web app open Settings → Workspace & API → API Keys, enter a Key name and choose Create key. The complete key starts with erppf_live_ and is shown only once — copy it into your secret store right away. ERP Preflight stores only a SHA-256 hash of the key; the key list shows its first 15 characters as prefix.

Keys created in the web app receive the default scopes projects:read, analyses:read, analyses:run, findings:read and reports:read: enough to upload files, run analyses, read findings and export reports from a pipeline. To choose other scopes, an expiry date or a request limit of its own, create the key through the API while signed in:

POST /api/v1/api-keys
{
  "name": "GitLab CI – S/4HANA upgrade",
  "scopes": ["projects:read", "projects:write", "analyses:read", "analyses:run", "findings:read", "reports:read"],
  "expiresAt": "2027-03-31T00:00:00Z",
  "rateLimitPerMinute": 120
}

name is required (up to 255 characters); scopes, expiresAt (ISO 8601) and rateLimitPerMinute (1 to 100 000) are optional. The response contains the key in apiKey — again only this once.

Send the key in the X-Api-Key header with every request to /api/v1:

curl -H "X-Api-Key: $ERP_PREFLIGHT_API_KEY" https://api.example.com/api/v1/projects

The key determines the organization. If a request also carries X-Tenant-Id, it must name the key's organization, otherwise it is rejected with HTTP 403. Requests made with a key act as the organization's API client on behalf of the user who created the key. They need no anti-forgery token.

Every route that API keys may call is mapped to one scope for reading (GET, HEAD, OPTIONS) and one for all other methods. The key must hold that scope; routes without a mapping are closed to API keys.

• projects:read — read projects, uploaded artifacts, the project object catalog, analysis templates and reference data (engine catalog, knowledge graph, knowledge articles, release intelligence).
• projects:write — create and update projects, API baselines, object imports, change sets, traceability links and analysis templates.
• analyses:read — read analyses and their progress, full-preflight runs and scheduled preflights.
• analyses:run — upload analysis inputs, start, cancel and re-run analyses, manage scheduled preflights and ask the problem router for engine suggestions.
• findings:read — read findings with their evidence, generated tests and the regression Test Lab.
• findings:write — change the lifecycle state of findings, comments and assignments, and manage regression tests.
• reports:read — generate and download reports and exports of an analysis, including the reproducibility bundle.
• landscapes:read — list registered SAP landscapes (system connections).
• landscapes:write — register and delete SAP landscapes and run connection tests.
• dashboard:read — read the organization's dashboard summary.
• webhooks:manage — manage webhook endpoints and their deliveries (see Webhooks).
• changes:propose — submit change proposals to the Agent Gate and execute approved proposals with their execution token.

The MCP endpoint accepts any key with at least one scope and checks the scope of each tool separately.

Whatever its scopes, a key cannot manage API keys, members, the account, billing, single sign-on and SCIM, data retention or the audit log; these operations always require an interactive sign-in.

The older scope names analysis:read and analysis:run are still accepted when a key is created; they are stored as analyses:read plus findings:read and as analyses:run.

• Expiry: a key created with expiresAt stops working at that time; requests then fail with HTTP 401. Keys without expiresAt do not expire.
• Last use: each successful authentication updates the key's last-use time, shown as Last used in the key list (last_used_at in GET /api/v1/api-keys).
• Revocation: choose Revoke in the key list or call DELETE /api/v1/api-keys/{id}. The key is rejected from the next request on; it stays in the list with the status Revoked.

To rotate a key, create a new one, update your secret store and then revoke the old key.

Each key has a budget of requests per minute: the rateLimitPerMinute set at creation, otherwise the operator default of 600 unless configured differently. Responses carry X-RateLimit-Limit; once the budget is used up, the API answers HTTP 429 with a Retry-After header.

• 401 — the key is unknown, revoked or expired.
• 403 API_KEY_SCOPE_DENIED — the key lacks the scope named in requiredScope.
• 403 — the route is closed to API keys (with the code API_KEY_NOT_ALLOWED for routes without a scope mapping).
• 429 RATE_LIMITED — the per-key budget is exhausted; retry after Retry-After seconds.