Docs

API Keys

How FlyDocs API keys work: authentication model, key generation, credential storage, security, and what keys cannot do.

Your API key is the primary connection between the FlyDocs CLI and the cloud platform. It authenticates every relay request. It does not carry configuration -- that lives on the workspace.

How keys work

Every CLI operation that touches your PM tool follows this request path:

  1. CLI reads the workspace ID from the committed .flydocs/config.json
  2. CLI sends Authorization: Bearer fdk_xxx and X-Workspace: ws_xyz headers to the relay
  3. Relay authenticates the key via SHA-256 hash lookup
  4. Relay verifies the user has membership in the requested workspace
  5. Relay loads workspace config: provider type, team, status mapping, labels, custom rules
  6. Relay decrypts provider credentials (AES-256-GCM) and calls the Linear or Jira API
  7. Result is returned to the CLI

The key proves who you are. The workspace header tells the relay what config to use. This separation is deliberate.

Key is auth, workspace is config

The API key handles authentication only. The workspace header handles configuration resolution. This separation means:

  • One key across all workspaces -- you do not need a separate key per workspace. Your single key authenticates you; the workspace header tells the relay which config to resolve.
  • Config changes take effect immediately -- update a status mapping or label in the portal, and every CLI session sees the change on the next request. No key rotation, no re-initialization.
  • Different providers per workspace -- Workspace A uses Linear, Workspace B uses Jira. The relay resolves provider config from the workspace, not from the key.

Generating a key

Go to Account > API Keys in the portal at app.flydocs.ai.

  1. Click Create New Key
  2. Enter a name to identify this key (e.g., "My IDE Key", "CI Pipeline")
  3. Click Generate

The key is displayed once. Copy it immediately -- it cannot be retrieved later. Only the key prefix (e.g., fdk_abc1def2) is stored for identification.

api key 
fdk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4...

Using your key

Three methods, in order of recommendation:

Global credentials (recommended)

Use flydocs init or flydocs auth to store your key at ~/.flydocs/credentials. This file is global to your machine and works across all projects.

terminal 
# During project setup
flydocs init

# Or update credentials directly
flydocs auth

Environment variable

Set FLYDOCS_API_KEY in your shell environment. Useful for CI/CD pipelines or ephemeral environments.

terminal 
export FLYDOCS_API_KEY=fdk_your_key_here

Project-scoped credentials

For projects that need a different key than your global default, use flydocs init --project-key. This stores the key in a project-local credentials file.

Resolution order

The CLI resolves credentials in this order. The first match wins:

  1. FLYDOCS_API_KEY environment variable
  2. Project-scoped credentials
  3. Global ~/.flydocs/credentials

Security model

Security

API keys are hashed with SHA-256 before storage. The plaintext key is never persisted on the server. The hash is used for lookup at request time. If you lose your key, it cannot be recovered -- revoke and generate a new one.

Key security details:

  • Keys are hashed immediately on creation. Only the hash exists in the database.
  • The fdk_ prefix makes keys identifiable in secret scanners and git pre-commit hooks.
  • Provider credentials (Linear/Jira OAuth tokens) are encrypted with AES-256-GCM, decrypted only per-request, and never exposed to the CLI.
  • Key revocation is immediate and irreversible -- all sessions using the revoked key fail on the next request.

Revoking a key

Go to Account > API Keys and click Revoke on the key you want to invalidate.

Revocation is immediate. All CLI sessions using this key stop working on the next request. There is no grace period. After revoking:

  1. Generate a new key in the portal
  2. Run flydocs auth to update your local credentials

What keys cannot do

API keys authenticate CLI operations against the relay. They do not grant administrative access. Keys cannot:

  • Create or delete workspaces
  • Change provider connections
  • Modify status mappings or label configuration
  • Manage team members or roles
  • Access billing or organization settings

These operations require the web portal. The CLI is read-only for configuration by design -- it keeps the portal as the single source of truth. Developers use their keys to read config and perform issue operations. Admins use the portal to manage the config those keys resolve.

Next