CLI API Keys & Authentication

The ivybloom CLI is the scriptable surface for the platform, and authentication is the first thing any automated workflow needs to establish. Reach for API keys when a script, CI/CD job, or integration must authenticate non-interactively — outside the browser OAuth flow used for hands-on work. They are the credential that lets your unattended pipelines call the platform securely; for the full command surface, see the CLI overview.

API Keys & Authentication

Manage authentication and API keys for CLI automation and integrations.

Authentication Methods

The ivybloom CLI supports four authentication methods:

Browser OAuth (Recommended)

ivybloom auth login --browser

Opens your default browser to authenticate. Best for interactive use.

API Key

ivybloom auth login --api-key ivy_yourKeyId_yourSecret

Best for automation, CI/CD, and headless servers.

Device Flow (Headless)

ivybloom auth login --device

For SSH sessions or servers without browsers. Follow the on-screen link to authenticate on another device.

CLI Linking

ivybloom auth link
ivybloom auth link --frontend-url https://custom.example.com

Opens browser, authenticates, and automatically generates an API key for this CLI installation. Use --frontend-url to specify a custom frontend for self-hosted deployments.

Which commands need an API key

Chat streams and tool calls need an API key (ivy_…). The CLI sends it as X-API-Key. A signed-in session token goes out as Authorization: Bearer instead. The CLI's client id is only a device label and never counts as a credential on its own: the server refuses a chat stream that has only a client id with 401 CLI_API_KEY_REQUIRED, and the CLI doesn't send a request that has no key or token.

• ivybloom in a terminal checks for a key at start. It opens the browser to link this installation when no key is stored, when the key has expired, or when the key expires within 3 days. A linked key lasts 30 days.
• ivybloom chat --headless, --script runs and ivybloom mcp serve never open a browser. With no usable key they exit with an error. Run ivybloom auth link first, or set IVYBLOOM_API_KEY.

Browser OAuth and device flow store a session token, not an API key, so the first terminal start after either one still links.

Why Use API Keys?

API keys are essential for:

• CI/CD Pipelines - Automate job submission in GitHub Actions, GitLab CI, etc.
• Scripting - Run batch analyses without interactive login
• Headless Servers - Authenticate on machines without browsers
• Integrations - Connect external tools to your platform account

Using API Keys

Environment Variable (Recommended)

export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
ivybloom jobs list

Via Login Command

ivybloom auth login --api-key ivy_yourKeyId_yourSecret

Managing Authentication

Check Status

ivybloom auth status
ivybloom auth status --check-connectivity   # Also verify API reachability
ivybloom auth status --show-permissions      # Show permission scopes

View Current User

ivybloom auth whoami

Force Re-Authentication

ivybloom auth login --force       # Invalidate existing token and re-authenticate
ivybloom auth login --no-verify   # Skip token verification after login

Logout

ivybloom auth logout
ivybloom auth logout --confirm    # Skip confirmation prompt

Device Management

List Linked Devices

ivybloom auth devices list
ivybloom auth devices list --format json

Revoke a Device

ivybloom auth devices revoke DEVICE_ID

Creating API Keys

Via Web Interface

1. Go to ivybiosciences.com/settings/api-keys
2. Click "Create New Key"
3. Enter a descriptive name
4. Copy the generated key (shown once only)

Via CLI Linking

ivybloom auth link

This automatically creates and configures an API key.

CI/CD Integration

GitHub Actions

name: Run Analysis

on: push

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ivybloom CLI
        run: |
          curl -fsSL https://www.ivybiosciences.com/install.sh | bash

      - name: Submit Job
        env:
          IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }}
        run: |
          ivybloom run esmfold protein_sequence=MKLVFFAEDV...

Setup:

1. Create an API key
2. Add as a repository secret named IVYBLOOM_API_KEY

GitLab CI

analyze:
  image: ubuntu:latest
  script:
    - curl -fsSL https://www.ivybiosciences.com/install.sh | bash
    - ivybloom run esmfold protein_sequence=MKLVFFAEDV...
  variables:
    IVYBLOOM_API_KEY: $IVYBLOOM_API_KEY

Jenkins

pipeline {
    environment {
        IVYBLOOM_API_KEY = credentials('ivybloom-api-key')
    }
    stages {
        stage('Analyze') {
            steps {
                sh 'curl -fsSL https://www.ivybiosciences.com/install.sh | bash'
                sh 'ivybloom run esmfold protein_sequence=MKLVFFAEDV...'
            }
        }
    }
}

Security Best Practices

ivybloom auth devices list

Troubleshooting

"Invalid API Key"

• Verify the key hasn't been revoked
• Check for typos (keys have the shape ivy_<keyId>_<secret>)
• Ensure no extra whitespace

"Insufficient Permissions"

Your API key may not have the required permissions. Create a new key with full access.

"Authentication Failed"

Try re-authenticating:

ivybloom auth logout
ivybloom auth login --browser

"CLI_API_KEY_REQUIRED" or "this CLI has no API key"

This CLI has no API key, or its linked key has expired. Link it again:

ivybloom auth link

"Device Not Found"

The device may have been revoked. Re-link the CLI:

ivybloom auth link

CLI Key Management

Manage API keys directly from the CLI:

ivybloom apikeys list
ivybloom apikeys create --name "ci-key" --scope read_write
ivybloom apikeys info KEY_ID
ivybloom apikeys update KEY_ID --name "new-name"
ivybloom apikeys revoke KEY_ID

API Key Scopes

API keys use three canonical capabilities (REST API):

The CLI also accepts legacy domain scopes for compatibility (e.g., jobs.read, data.write), which map to the canonical capabilities above.

Default: Omitting --scopes creates a key with read and write access (not manage). To add manage, pass --scopes read write manage explicitly.

Top-Level Device Management

In addition to auth devices, there are top-level device commands:

ivybloom devices list
ivybloom devices trust DEVICE_ID
ivybloom devices untrust DEVICE_ID
ivybloom devices remove DEVICE_ID

Read next

• Configuration — Set up CLI defaults
• Organizations — Team-scoped authentication
• Agent Mode — CI/CD automation patterns
• FAQ — Common questions