API Keys

API keys authenticate programmatic access to Supaflow - from the CLI and from external systems such as orchestrators (Airflow, Azure Data Factory), CI jobs, and scripts.

A key is scoped to the organization (workspace) it is created in, and its value starts with ak_.

Looking for the older tokens?

If you previously used long eyJ... Personal Access Tokens, those are now the Legacy API Keys and are deprecated. Use the ak_ keys described here for new integrations.

Enable API access first

Administrator action required

Access is off by default. An organization administrator or personal-account owner must enable it for the intended account before using the CLI, API, or hosted AI integration. Being an administrator does not bypass a disabled setting.

When access is disabled, the default Keys tab shows a message and a Configure access link:

1. Sign in to Supaflow and select the intended organization or personal account.

2. Open Settings > API Keys. If keys are disabled, choose Configure access or the Permissions tab.

3. Check Enable API access.

4. Select only the methods you want to allow:

   Connection method	Required selection
   API keys, scripts, or CLI login with a key	Allow API keys
   CLI browser login or local CLI-backed MCP using OAuth	Supaflow CLI under OAuth applications
   Hosted ChatGPT integration	ChatGPT under OAuth applications
   Hosted Claude integration	Claude under OAuth applications

5. Click Save changes, review the enabled and disabled permissions, then click Save access settings.

6. For key-based access, return to the Keys tab to create or manage keys. For OAuth, connect or retry login in the selected application.

The Permissions tab starts with API access off and the other options disabled:

Select the methods your account needs. This example shows every method selected; OAuth-only setups should leave Allow API keys unchecked:

Click Save changes to review the selections. Nothing is enabled until you confirm with Save access settings:

The master switch alone allows no connection method. API keys are not required for OAuth: leave Allow API keys unchecked if you want OAuth-only access. Unchecked and unknown OAuth applications are denied. A key can still be used by the CLI or custom tools even when Supaflow CLI OAuth is unchecked; that checkbox controls browser OAuth login, not every possible use of the CLI executable.

Only administrators and personal-account owners can manage these settings and use the supported programmatic access paths. If you cannot open the page, contact your organization administrator.

Disabling access

Turning off Enable API access disables API-key exchanges and all selected OAuth applications. Reenabling requires selecting the methods again. Removing a method blocks new credential exchanges; general-purpose access tokens already issued can remain valid for up to one hour. Hosted MCP checks the current policy on subsequent requests. A successful OAuth connection label alone does not establish permission to use tools.

Existing system agents, OTP enrollment and recovery, and web-issued OTPs remain independent of these settings. Use the dashboard's agent deployment workflow when API access is disabled; CLI-managed setup still needs its own permitted CLI authentication.

If login or a tool call is denied, check the active account, administrator role, master switch, method selection, and saved review before reconnecting. Never paste keys or tokens into chat.

Create an API key

1. Complete Enable API access first, including Allow API keys, then open Settings > API Keys > Keys.
2. Click Add new key and give it a descriptive name that identifies where it will be used - for example Airflow trigger, Production CI/CD, or ADF trigger.
3. Copy the key value. It starts with ak_ and is shown only once - store it in a secret manager immediately. If you lose it, create a new key.

Keys are scoped to the organization they are created in, so a key can only access pipelines, datasources, and jobs in that workspace.

Use a key with the CLI

The Supaflow CLI is the most common way to use a key. Authenticate once, then select your workspace:

supaflow auth login --key ak_XXXXXXXXXXXXXXXXXXXX
supaflow workspaces select "My Workspace"

From there you can list and run pipelines, inspect jobs, manage datasources, and more. The CLI stores the key in its local config and handles token exchange for you.

Use a key with the API

Calling the API directly is a two-step exchange:

1. Send the ak_ key to the bootstrap endpoint. The response returns a short-lived access token (valid one hour), plus the supabase_url (API host) and supabase_anon_key (public key) for your region.

   curl -sS -X POST https://app.supa-flow.io/api/cli/bootstrap \
     -H "Authorization: Bearer ak_XXXXXXXXXXXXXXXXXXXX"

2. Make subsequent calls against the returned supabase_url, sending both headers: the token as Authorization: Bearer <token> and the supabase_anon_key as apikey: <supabase_anon_key>. Both are required - omitting the apikey header causes auth failures.

For a complete, worked example - triggering a pipeline run and polling it to completion - see Trigger a pipeline run via the API. The API Reference overview documents the authentication model in full.

Manage and revoke keys

On the Settings -> API Keys page you can see each key's name, a masked preview, when it was created, and when it was last used.

Revoke a key when:

• it may have been exposed or committed somewhere it should not have been;
• the application or integration using it is decommissioned;
• it has not been used in a long time and is no longer needed.

Revoking prevents further exchanges with that key. Access tokens already issued from it can remain valid until they expire, for up to one hour.

Security best practices

• Treat the key like a password. Anyone with the key has the same access as the key's scope.
• Never commit a key to version control. Load it from an environment variable or a secret manager (Azure Key Vault, AWS Secrets Manager, GitHub Actions secrets, 1Password, etc.).
• Use a separate key per integration and environment. That way you can revoke one without disrupting the others, and the name + "last used" column tell you what each key is for.
• Rotate periodically, and immediately if a key may have been exposed: create a new key, update the consumer, verify it works, then revoke the old one.

Related pages

• Trigger a pipeline run via the API - the most common automation use case
• API Reference - authentication and available operations
• CLI - the supaflow command-line tool
• Legacy API Keys - the deprecated Personal Access Token system

Support

Questions about API keys? Contact us at support@supa-flow.io.