Authentication

Overview

The CodeThreat API uses API keys to authenticate requests. You can generate and manage your API keys from your organization settings in the CodeThreat dashboard.

Keep your API keys secure! Never commit API keys to source control or expose them in client-side code.

Getting Your API Key

Navigate to Settings

Log into your CodeThreat dashboard and go to Organization Settings → API Keys.

Generate New Key

Click Generate API Key and provide a descriptive name (e.g., “CI/CD Pipeline”, “Development”).

Copy and Store Securely

Copy the generated API key immediately. For security, it won’t be shown again.

Configure Your Requests

Include the API key in the X-API-Key header of all API requests.

Making Authenticated Requests

Include your API key in the X-API-Key header:

curl --request GET \
  --url 'https://app.codethreat.com/api/v1/organizations' \
  --header 'X-API-Key: YOUR_API_KEY'

const response = await fetch('https://app.codethreat.com/api/v1/organizations', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Environment Variables

Store API keys as environment variables for security:

export CODETHREAT_API_KEY="your_api_key_here"

curl --request GET \
  --url 'https://app.codethreat.com/api/v1/organizations' \
  --header "X-API-Key: $CODETHREAT_API_KEY"

Error Responses

401 Unauthorized

Missing or invalid API key:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1",
    "requestId": "req_123456"
  }
}

403 Forbidden

Valid API key but insufficient permissions:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1",
    "requestId": "req_123456"
  }
}

API Key Best Practices

Rotate Regularly

Rotate API keys every 90 days or when team members leave

Use Descriptive Names

Name keys by purpose: “Production CI/CD”, “Staging Environment”

Scope Appropriately

Use the minimum required permissions for each key

Monitor Usage

Track API key usage in your audit logs

Validate Your API Key

Test your API key with the CLI validation endpoint:

curl --request GET \
  --url 'https://app.codethreat.com/api/v1/cli/auth/validate' \
  --header 'X-API-Key: YOUR_API_KEY'

Success Response:

{
  "success": true,
  "data": {
    "valid": true,
    "user": {
      "id": "usr_123",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "organizations": [...],
    "permissions": ["read:scans", "write:scans"],
    "authenticatedAt": "2025-01-15T10:30:00Z"
  }
}

Getting Started

Core Resources

Developer Tools

Overview

Getting Your API Key

Making Authenticated Requests

Environment Variables

Error Responses

401 Unauthorized

403 Forbidden

API Key Best Practices

Rotate Regularly

Use Descriptive Names

Scope Appropriately

Monitor Usage

Validate Your API Key

Next Steps

Explore API

CI/CD Integration

​Overview

​Getting Your API Key

​Making Authenticated Requests

​Environment Variables

​Error Responses

​401 Unauthorized

​403 Forbidden

​API Key Best Practices

Rotate Regularly

Use Descriptive Names

Scope Appropriately

Monitor Usage

​Validate Your API Key

​Next Steps

Explore API

CI/CD Integration

Overview

Getting Your API Key

Making Authenticated Requests

Environment Variables

Error Responses

401 Unauthorized

403 Forbidden

API Key Best Practices

Validate Your API Key

Next Steps