API keys authenticate the Vidoc CLI and API requests. Each key is scoped to a specific project.
Creating an API Key
- Go to your project
- Navigate to Settings → API Keys
- Click “Create API Key”
- Enter a name (e.g., “CI/CD Pipeline”, “Local Development”)
- Click “Create”
- Copy the key immediately
The API key is only shown once. Store it securely before closing the dialog.
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
# 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:
curl -H "Authorization: Bearer your-api-key" \
https://api.vidocsecurity.com/v1/scan-workflows/start
Managing API Keys
View Keys
- Go to Settings → API Keys
- See all keys for the project
- Check last used timestamps
Revoke a Key
- Find the key in the list
- Click “Revoke”
- Confirm revocation
Revoking a key immediately invalidates it. CI/CD pipelines using the key will fail.
Rotate Keys
To rotate a key:
- Create a new key
- Update your CI/CD pipelines with the new key
- Verify scans work with the new key
- Revoke the old key
Best Practices
Use Descriptive Names
Name keys by their purpose:
github-actions-prodgitlab-ci-staginglocal-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.
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 |
Troubleshooting
”Invalid API key”
- Verify the key was copied correctly
- Check for extra whitespace
- Ensure the key hasn’t been revoked
- Verify you’re using the right project’s key
”API key expired”
API keys don’t expire automatically. If you see this error:
- The key may have been revoked
- Create a new key
”Rate limit exceeded”
- Reduce scan frequency
- Check for duplicate CI/CD triggers
- Contact support for limit increase
Related Pages
