> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create and manage API keys for CLI and CI/CD integration

API keys authenticate the Vidoc CLI and API requests. Each key is scoped to a specific project.

## Creating an API Key

1. Go to your project
2. Navigate to **Settings** → **API Keys**
3. Click **"Create API Key"**
4. Enter a name (e.g., "CI/CD Pipeline", "Local Development")
5. Click **"Create"**
6. Copy the key immediately

<Warning>
  The API key is only shown once. Store it securely before closing the dialog.
</Warning>

## API Key Properties

| Property        | Description                           |
| --------------- | ------------------------------------- |
| **Name**        | Descriptive label for identification  |
| **Project**     | The project this key authenticates to |
| **Created**     | When the key was created              |
| **Last Used**   | Most recent API call with this key    |
| **Permissions** | All keys have full project access     |

## Using API Keys

### CLI Authentication

```bash theme={null}
# Interactive login
vidoc login
# Enter your API key when prompted

# Direct login
vidoc login your-api-key

# Environment variable (recommended for CI/CD)
export VIDOC_API_KEY=your-api-key
vidoc scan
```

### API Authentication

Include the key in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer your-api-key" \
  https://api.vidocsecurity.com/v1/scan-workflows/start
```

## Managing API Keys

### View Keys

1. Go to **Settings** → **API Keys**
2. See all keys for the project
3. Check last used timestamps

### Revoke a Key

1. Find the key in the list
2. Click **"Revoke"**
3. Confirm revocation

<Warning>
  Revoking a key immediately invalidates it. CI/CD pipelines using the key will fail.
</Warning>

### Rotate Keys

To rotate a key:

1. Create a new key
2. Update your CI/CD pipelines with the new key
3. Verify scans work with the new key
4. Revoke the old key

## Best Practices

### Use Descriptive Names

Name keys by their purpose:

* `github-actions-prod`
* `gitlab-ci-staging`
* `local-dev-alice`

### One Key Per Purpose

Create separate keys for:

* Each CI/CD pipeline
* Each developer (for local development)
* Each environment

This allows granular revocation if a key is compromised.

### Secure Storage

| Environment        | Storage Method                        |
| ------------------ | ------------------------------------- |
| **GitHub Actions** | Repository Secrets                    |
| **GitLab CI**      | CI/CD Variables (masked)              |
| **Local**          | Environment variable or `vidoc login` |
| **Jenkins**        | Credentials plugin                    |

### Regular Rotation

Rotate keys periodically:

* Every 90 days for production
* After team member departure
* After any suspected compromise

## Permissions

All API keys have full access to their project:

* Start scans
* View issues
* Access scan results

Project-level permissions are managed through [Team Members](/settings/team-members).

## Rate Limits

API calls are rate-limited per project:

| Operation   | Limit          |
| ----------- | -------------- |
| Start scan  | 10 per minute  |
| Get status  | 100 per minute |
| List issues | 100 per minute |

Contact support if you need higher limits.

## Troubleshooting

### "Invalid API key"

1. Verify the key was copied correctly
2. Check for extra whitespace
3. Ensure the key hasn't been revoked
4. Verify you're using the right project's key

### "API key expired"

API keys don't expire automatically. If you see this error:

1. The key may have been revoked
2. Create a new key

### "Rate limit exceeded"

1. Reduce scan frequency
2. Check for duplicate CI/CD triggers
3. Contact support for limit increase

## Related Pages

<CardGroup cols={2}>
  <Card title="CLI Authentication" icon="key" href="/cli/authentication">
    CLI login methods
  </Card>

  <Card title="CI/CD Integration" icon="gear" href="/cli/ci-cd">
    Pipeline setup
  </Card>

  <Card title="Team Members" icon="users" href="/settings/team-members">
    Manage access
  </Card>

  <Card title="API Reference" icon="code" href="/api/authentication">
    API documentation
  </Card>
</CardGroup>