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.

Create an API key

1. Go to Settings -> API 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 takes effect immediately - any system still using that key will start receiving authentication errors on its next request.

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.