---
title: CLI API Keys & Authentication
description: Manage authentication and API keys for CLI automation and integrations.
tags:
  - authentication
  - api-keys
  - ci-cd
  - security
---

  beginner

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](/docs/cli).

## 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)

```bash
ivybloom auth login --browser
```

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

### API Key

```bash
ivybloom auth login --api-key ivy_yourKeyId_yourSecret
```

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

### Device Flow (Headless)

```bash
ivybloom auth login --device
```

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

### CLI Linking

```bash
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)

```bash
export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
ivybloom jobs list
```

### Via Login Command

```bash
ivybloom auth login --api-key ivy_yourKeyId_yourSecret
```

> **Security Warning**

> Avoid storing API keys in config files that may be committed to version control.

---

## Managing Authentication

### Check Status

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

### View Current User

```bash
ivybloom auth whoami
```

### Force Re-Authentication

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

### Logout

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

---

## Device Management

### List Linked Devices

```bash
ivybloom auth devices list
ivybloom auth devices list --format json
```

### Revoke a Device

```bash
ivybloom auth devices revoke DEVICE_ID
```

> Revoking a device immediately invalidates its session. Any scripts using that device's credentials will stop working.

---

## Creating API Keys

### Via Web Interface

1. Go to [ivybiosciences.com/settings/api-keys](https://www.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

```bash
ivybloom auth link
```

This automatically creates and configures an API key.

---

## CI/CD Integration

### GitHub Actions

```yaml
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

```yaml
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

```groovy
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

#### Use environment variables

Never hardcode API keys in scripts or config files that are version controlled.

#### Use CLI linking

CLI linking creates device-specific credentials that can be revoked individually.

#### Rotate regularly

Replace keys periodically or when team members leave.

#### Use separate keys per environment

Create different keys for development, staging, and production.

#### Monitor devices

Check linked devices regularly:
```bash
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:
```bash
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:
```bash
ivybloom auth link
```

### "Device Not Found"

The device may have been revoked. Re-link the CLI:
```bash
ivybloom auth link
```

---

## CLI Key Management

Manage API keys directly from the CLI:

```bash
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):

| Scope | Description |
|-------|-------------|
| `read` | Read operations (list, view, download) |
| `write` | Write operations (submit, upload, create, modify) |
| `manage` | Admin operations (revoke keys, manage access) |

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:

```bash
ivybloom devices list
ivybloom devices trust DEVICE_ID
ivybloom devices untrust DEVICE_ID
ivybloom devices remove DEVICE_ID
```

---

## Read next

- [Configuration](/docs/cli/configuration) — Set up CLI defaults
- [Organizations](/docs/cli/organizations) — Team-scoped authentication
- [Agent Mode](/docs/cli/agent-mode) — CI/CD automation patterns
- [FAQ](/docs/cli/faq) — Common questions