Organization API Keys

Global API keys let you automate Zenifra operations without using a user's personal session. Each key belongs to an organization, records who created it, respects RBAC, and can be restricted by source IP.

Use this feature for CI/CD, internal scripts, operational jobs, and server-side integrations.

Create an API key

In the organization console:

1. open API Keys;
2. click Create API key;
3. enter a descriptive name;
4. choose the required permissions;
5. optionally configure allowed IPs and expiration;
6. copy the key shown after creation.

The full key is shown only once. After that, the console shows only metadata and the key preview.

Use in HTTP requests

Send the API key in an authentication header:

curl https://api.zenifra.com/v1/project \
  -H "Authorization: Bearer znf_your_key"

This header is also accepted:

curl https://api.zenifra.com/v1/project \
  -H "x-api-key: znf_your_key"

Prefer Authorization: Bearer for compatibility with the CLI and common HTTP tools.

Use with the CLI

In automations, use an environment variable:

export ZENIFRA_API_KEY=znf_your_key
zenifra projects --type http --page 1 --limit 15
zenifra deploy --project <project-id> --branch main

To save it locally:

zenifra auth api-key --key znf_your_key

Because the API key is already linked to an organization, automation commands do not need org set. Personal commands, such as listing organizations, still require user login.

Permissions and scope

The API key uses the same organization permission model. Grant only what the automation needs.

Examples:

• deploy a specific project;
• read logs and metrics;
• create projects from a pipeline;
• inspect builds;
• rotate controlled operational resources.

If a key leaks, the impact is limited by the granted permissions and allowed IPs.

IP allowlist

When creating the key, enter fixed IPs that may call the API. When the list is not empty, requests from other IPs are rejected.

Use IP allowlists when automation runs on:

• self-hosted runners;
• internal servers;
• corporate NAT;
• jobs with a known egress IP.

The field accepts literal IPv4 and IPv6 addresses. CIDR is not accepted.

Revocation and rotation

Revoke a key when:

• it is no longer used;
• its owner left the team;
• the source IP changed;
• a leak is suspected;
• the permissions became too broad.

For safe rotation, create a new key, update the automation, validate usage, and revoke the old key.

Next steps

• Granular permissions in organizations
• Deploy and automation CLI
• Security in Zenifra