Authentication

Overview

Metroflow supports two primary authentication modes for the REST API. Both resolve to a Bearer token presented on each request.

API keys

API keys are long-lived secrets scoped to a workspace and role. They inherit the permissions of the user or service account that created them.

• Prefix: mf_live_ (production) or mf_test_ (sandbox workspace)
• Length: 32-character random suffix after the prefix
• Scopes: read, write, admin; assign the minimum scope needed
• Expiry: Optional TTL (30, 90, 365 days) or no expiry with mandatory rotation policy

API keys are shown once at creation. Store them in a secrets manager; Metroflow only stores a salted hash.

OAuth & service accounts

For integrations that cannot store a static key, register an OAuth client in Settings → API → Service accounts. Metroflow implements the OAuth 2.0 client credentials grant.

1. Create a service account

   Assign a role (analyst, engineer, or admin) and note the client_id and client_secret.

2. Exchange credentials for an access token

   POST to the token endpoint. Access tokens expire in 3600 seconds; refresh by requesting a new token before expiry.

   token exchange copy

   $curl -s -X POST "https://your-metroflow-host/oauth/token" \

   -H "Content-Type: application/x-www-form-urlencoded" \

   -d "grant_type=client_credentials" \

   -d "client_id=sa_4f8c2a1b9e7d" \

   -d "client_secret=$CLIENT_SECRET" \

   -d "scope=read write"

   { "access_token": "eyJhbG...", "token_type": "Bearer", "expires_in": 3600 }
3. Use the access token as a Bearer token

   Identical header format to API keys. No refresh token is issued; request a new access token when expires_in elapses.

Creating tokens

Workspace admins and users with the api:manage permission can create tokens from the UI.

1. Open workspace Settings

   Sign in to the workspace at https://your-metroflow-host (or http://localhost:4200 locally).

2. Navigate to Settings → API

   The API panel lists active tokens, service accounts, and audit logs for token usage.

3. Click Create API token

   Name the token (e.g. github-actions-lineage), choose scope and optional expiry, then confirm.

4. Copy the token immediately

   The full secret is displayed once. Paste it into your secrets manager before closing the dialog.

   example token

   mf_live_7f3a9c2e1b4d8a6f0e5c3b9a2d7f1e4

Bearer header format

All authenticated API requests must include the Authorization header. The scheme is always Bearer followed by a single space and the token value.

Malformed headers (missing Bearer, extra quotes, or newline characters) return 401 unauthorized with error code invalid_auth_header.

Request examples

Verify your token with a catalog query. Replace the host and token with your deployment values.

Health check (no auth)

Authenticated catalog request

Agent query with context

Trigger connector sync

See the full endpoint reference in the REST API guide.

Token rotation best practices

Rotate credentials on a schedule and immediately after any suspected compromise. Metroflow supports overlapping tokens so rotation does not cause downtime.

1. Create a new token before revoking the old one

   Issue the replacement in Settings → API, deploy it to your secrets manager, and validate with a read-only endpoint.

2. Update all consumers

   Roll out the new secret to CI variables, Airflow connections, and Kubernetes secrets. Use distinct tokens per consumer to narrow blast radius.

3. Revoke the previous token

   Revocation is immediate; outstanding requests with the old token receive 401. Audit logs record the revoking user and timestamp.

4. Enforce expiry policies

   Admins can require maximum token TTL (e.g. 90 days) at the workspace level. Expired tokens cannot be renewed; create a new token instead.

Self-hosted OIDC

Self-hosted Metroflow deployments can delegate workspace UI login to an OpenID Connect provider (Okta, Azure AD, Google Workspace, or any OIDC-compliant IdP). API authentication remains Bearer-based; OIDC governs browser sessions only.

Configure OIDC in your .env or Helm values:

Map IdP groups to Metroflow roles in Settings → Access → SSO mappings. Users who authenticate via OIDC can still create API tokens from the workspace UI once logged in.

Security checklist

Before exposing the API beyond your VPC, confirm these controls are in place.

• TLS everywhere: Terminate HTTPS at your ingress; never send tokens over plain HTTP in production
• Least privilege: Use read-scoped tokens for dashboards and lineage queries; reserve write for sync triggers
• Secrets storage: AWS Secrets Manager, HashiCorp Vault, or GitHub encrypted secrets, never .env files in repos
• Audit logs: Review Settings → API → Audit weekly for anomalous IPs or spike in 403 responses
• Network policy: Restrict API ingress to CI runners and internal subnets via security groups or Kubernetes NetworkPolicy
• IP allowlists: Optional workspace-level CIDR allowlist for API tokens (Enterprise)