Start free trial
Sign in Start free trial

API keys

API keys let you integrate Dependra into your CI/CD pipelines, scripts, monitoring tooling, and AI agents. With a scoped key you can read the landscape, upsert entities, push health signals, and drive the MCP server.

Note

API & MCP access is a Business+ capability. Keys are created on the Business tier and above.

Creating an API key

  1. Sign in to dependra.io with an Admin or Owner role.
  2. Open Settings → API Keys.
  3. Click Create API Key.
  4. Configure the key:
    • Name — a descriptive label (e.g., “CI Pipeline — Production”).
    • Scopes — one or more of read, write, health (grant the least you need).
    • Expiration — how long the key is valid.
  5. Copy the key immediately — it starts with dep_ and is shown only once.
Warning

Keys are displayed once, at creation. Dependra stores only a secure hash, never the raw key. If you lose a key, revoke it and create a new one.

Scopes

Keys are governed by their scopes, not by membership RBAC. A request outside a key’s scopes is rejected with 403.

Scope Grants
read Read the landscape (revenue/economics fields subject to plan + visibility)
write Create, update and delete landscape entities
health Push component health signals to the ingestion endpoint
manifest-sync Sync a repository’s .dependra/manifest.yaml into the landscape
Note

manifest-sync is not offered in the key-creation picker — it is normally minted for you, short-lived and single-use, by the GitHub Action’s OIDC exchange. Use a static manifest-sync key only where OIDC is unavailable.

Key properties

Property Details
Prefix dep_
Tenant scope Carries a tenant claim — a key can only access its own tenant
Visibility Shown once at creation; stored as a SHA-256 hash
Revocation Admins/Owners can revoke any key at any time

Managing keys

From Settings → API Keys you can:

  • View active keys — name, scopes, creation and expiration dates.
  • Rotate a key — create a replacement, update your integrations, then revoke the old one.
  • Revoke a key — immediately invalidate it. Revoked keys cannot be restored.

Rotation best practices

  1. Scope down — a monitoring integration needs only health; a query bot only read.
  2. Use descriptive names — include the environment and purpose (“GitHub Actions — Staging”).
  3. Rotate before expiration — create the new key, cut over, then revoke the old one.
Tip

Treat API keys like passwords. Never commit them to version control — use environment variables or your platform’s secrets management.

Rate limits

Health-signal ingestion is rate-limited per plan; exceeding it returns 429 with a Retry-After header. Higher tiers receive higher caps.

Next steps

Learn how to authenticate your requests, explore the API examples, or connect an agent with the MCP quickstart.