# API Keys

Source: https://docs.ops0.com/docs/settings/api-keys

API keys allow programmatic access to ops0 — for CLI tools, CI/CD pipelines, scripts, and third-party integrations. Each key is scoped to a specific set of permissions so you can follow the principle of least privilege.

---

## Creating an API Key

### Navigate to API Keys
Go to **Settings** > **API Keys** > **New Key**.

### Name the Key
Enter a descriptive name so you can identify the key later (e.g. `github-actions-deploy`, `monitoring-readonly`).

### Select Scopes
Choose the scopes this key needs. Grant only the access required for the intended use case.

### Create
Click **Create**. The key secret is displayed once — copy it immediately.

**Key Shown Once**

The full API key secret is only displayed at creation time. Copy it to a secrets manager immediately — ops0 does not store it in a retrievable form after this point.

---

## Key Scopes

| Scope | Access |
|-------|--------|
| `read` | Read resources, sessions, deployments, and projects |
| `write` | Create and update projects, trigger scans and deployments |
| `admin` | Full access including user management and settings |

Use `read` for monitoring tools, `write` for CI/CD pipelines, and `admin` only for fully trusted automation that needs to manage users or org settings.

---

## Using API Keys

Pass the key as a Bearer token in the `Authorization` header on every request:

```bash
curl -X GET https://api.ops0.ai/v1/projects \
  -H "Authorization: Bearer ops0_live_xxxxxxxxxxxxxxxxxxxx"
```

All API endpoints follow REST conventions. Refer to the [API Reference](https://docs.ops0.com/docs/api) for available endpoints and request/response schemas.

---

## API Keys Page Layout

The **Settings → API Keys** page has three views, selectable from the toggle at the top:

| View | Description |
|------|-------------|
| **Keys** | List of all API keys — create, rotate, revoke |
| **Activity** | Recent API calls made using keys in your org — timestamp, key name, endpoint, status code |
| **Insights** | Usage trends — calls per key over time, most-used endpoints, error rates |

Use Activity to audit API usage and investigate unexpected calls. Use Insights to identify unused keys that can be safely revoked.

---

## Managing Keys

Go to **Settings** > **API Keys** > **Keys** to see all keys for your organization. The list shows:

| Column | Description |
|--------|-------------|
| **Name** | Descriptive label |
| **Scopes** | Assigned permission scopes |
| **Created** | Creation date and creator |
| **Last Used** | Timestamp of most recent API call |
| **Status** | Active or Revoked |

### Rotate a Key

Rotation generates a new secret for the key while keeping its name and scopes. The old secret continues to work for **24 hours** after rotation to give you time to update dependent systems.

### Open Key Actions
Click the **...** menu next to the key you want to rotate.

### Rotate
Select **Rotate Key**.

### Copy New Secret
The new secret is displayed once. Copy it immediately.

### Update Dependent Systems
Replace the old key value in all services, CI/CD pipelines, and secrets managers before the 24-hour grace period ends.

### Revoke a Key

Revocation permanently disables the key with no grace period. Use this immediately if a key is suspected to be compromised.

### Open Key Actions
Click the **...** menu next to the key.

### Revoke
Select **Revoke Key** and confirm the action.

### Result
The key is immediately invalidated. All API calls using it will receive a `401 Unauthorized` response.

---

## Security Best Practices

**Security Best Practices**

  - Grant the **minimum required scope** — use `read` unless writes are needed.
  - Rotate keys on a regular schedule (e.g. every 90 days).
  - **Never commit API keys to git** — use environment variables or secrets managers.
  - Create **one key per service** rather than sharing a single key across multiple systems. This limits blast radius if a key is compromised and makes it easy to revoke access for a specific service.

---

## CI/CD Integration

Store the API key as an encrypted secret in your CI/CD system and inject it as an environment variable at runtime.

### GitHub Actions

```yaml
# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger ops0 deployment
        env:
          OPS0_API_KEY: ${{ secrets.OPS0_API_KEY }}
        run: |
          curl -X POST https://api.ops0.ai/v1/projects/my-project/deploy \
            -H "Authorization: Bearer $OPS0_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"environment": "production"}'
```

Add the key to your repository under **Settings** > **Secrets and variables** > **Actions** > **New repository secret** with the name `OPS0_API_KEY`.

---

## Related

- [IAM & Roles](https://docs.ops0.com/docs/settings/iam): Manage users, roles, and permissions for your organization.

- [Audit Logs](https://docs.ops0.com/docs/settings/audit-logs): Review all API activity and access events.