DeployBrief DeployBrief
← Back to Documentation

API Authentication

Create and manage API keys for secure programmatic access to DeployBrief.

Overview

API keys provide secure, programmatic access to DeployBrief for automation, CI/CD integration, and custom tooling. Each key has specific scopes that control what actions it can perform.

Key Format: API keys start with db_ followed by a random string (e.g., db_1234567890abcdef)

Creating API Keys

Only Owners and Admins can create API keys:

  1. Navigate to Settings → API Keys
  2. Click Create API Key
  3. Configure the key:
    • Name: Descriptive name (e.g., "GitHub Actions", "Production CI")
    • Description: Optional notes about usage
    • Scopes: Select permissions (see below)
    • Expiration: Choose expiry date or "Never" (not recommended)
  4. Click Generate Key
  5. Copy the key immediately - you won't be able to view it again

Important: Store your API key securely! Treat it like a password. If lost, you must create a new key.

API Key Scopes

Scopes control what actions an API key can perform. Follow the principle of least privilege.

briefs:read

View existing deployment briefs. Required for listing and retrieving briefs.

Endpoints: GET /api/briefs, GET /api/briefs/{id}

briefs:write

Generate new deployment briefs. Required for automated brief generation in CI/CD.

Endpoints: POST /api/briefs/generate, POST /api/briefs/generate-from-preset

briefs:delete

Delete deployment briefs. Use cautiously; typically not needed for automation.

Endpoints: DELETE /api/briefs/{id}

connections:read

View Azure DevOps connections. Useful for discovering available connections.

Endpoints: GET /api/connections

presets:read

View pipeline presets. Required for preset-based brief generation.

Endpoints: GET /api/presets

Recommended Scope Combinations

CI/CD Pipeline (Recommended)

briefs:write, briefs:read, presets:read

Read-Only Dashboard

briefs:read, connections:read, presets:read

Full Automation (Use Carefully)

briefs:*, connections:read, presets:read

Using API Keys

Include your API key in the Authorization header as a Bearer token:

cURL Example

curl https://api.deploybrief.com/api/briefs \
  -H "Authorization: Bearer db_1234567890abcdef"

JavaScript/TypeScript

const response = await fetch('https://api.deploybrief.com/api/briefs', {
  headers: {
    'Authorization': `Bearer $${process.env.DEPLOYBRIEF_API_KEY}`,
    'Content-Type': 'application/json'
  }
}});

Python

import requests
import os

headers = {
    'Authorization': f'Bearer {os.getenv("DEPLOYBRIEF_API_KEY")}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.deploybrief.com/api/briefs', headers=headers)

PowerShell

$headers = @{
    'Authorization' = "Bearer $env:DEPLOYBRIEF_API_KEY"
    'Content-Type' = 'application/json'
}

Invoke-RestMethod -Uri 'https://api.deploybrief.com/api/briefs' -Headers $headers

Managing API Keys

Viewing Active Keys

See all active API keys for your workspace:

  1. Navigate to Settings → API Keys
  2. View list showing:
    • Key name and description
    • Scopes
    • Creation date
    • Last used timestamp
    • Expiration date

Revoking Keys

Immediately invalidate an API key:

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click Revoke
  4. Confirm revocation

Warning: Revoking a key immediately stops all integrations using it. Update your CI/CD pipelines before revoking.

Rotating Keys

Best practice: rotate keys periodically (every 90 days recommended):

  1. Create a new API key with the same scopes
  2. Update all integrations to use the new key
  3. Test that integrations work with the new key
  4. Revoke the old key

CI/CD Integration

API keys are essential for integrating DeployBrief into your CI/CD pipelines.

GitHub Actions

# Store API key as GitHub secret: DEPLOYBRIEF_API_KEY

- name: Generate Deployment Brief
  run: |
    curl -X POST https://api.deploybrief.com/api/briefs/generate-from-preset \
      -H "Authorization: Bearer $${{secrets.DEPLOYBRIEF_API_KEY}}" \
      -H "Content-Type: application/json" \
      -d '{"presetId": "preset-123", "buildId": $${{github.run_id}}}'

Azure Pipelines

# Store API key as pipeline variable: DEPLOYBRIEF_API_KEY

- task: PowerShell@2
  displayName: 'Generate Deployment Brief'
  inputs:
    targetType: 'inline'
    script: |
      $headers = @{
        'Authorization' = "Bearer $(DEPLOYBRIEF_API_KEY)"
        'Content-Type' = 'application/json'
      }
      Invoke-RestMethod -Uri 'https://api.deploybrief.com/api/briefs/generate-from-preset' `
        -Method Post -Headers $headers `
        -Body (@{presetId = 'preset-123'; buildId = $(Build.BuildId)}| ConvertTo-Json)

See CI/CD Integration Guide for complete examples.

Security Best Practices

  • Never commit API keys to source control: Use environment variables or secrets management.
  • Use minimal scopes: Grant only necessary permissions for each integration.
  • Set expiration dates: Prefer time-limited keys (90 days recommended).
  • Rotate regularly: Create new keys and revoke old ones periodically.
  • Monitor usage: Review "last used" timestamps to detect unauthorized access.
  • Revoke immediately if compromised: If a key is leaked, revoke it instantly.
  • Use separate keys per integration: Easier to track and revoke specific integrations.
  • Store securely: Use secrets managers (Azure Key Vault, AWS Secrets Manager, GitHub Secrets).

Troubleshooting

401 Unauthorized

  • Verify API key is correct (no extra spaces or characters)
  • Check key hasn't been revoked
  • Ensure key hasn't expired
  • Confirm Authorization: Bearer format is correct

403 Forbidden

  • Check API key has required scopes for the endpoint
  • Verify you're accessing resources in your workspace
  • Confirm key wasn't created for a different workspace

429 Rate Limit Exceeded

  • Implement exponential backoff in your integration
  • Check rate limit headers in responses
  • Reduce request frequency
  • Contact support for higher rate limits if needed

Next Steps