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

# Authentication

> Secure your API requests with API keys

## 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](https://app.codethreat.com).

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

***

## Getting Your API Key

<Steps>
  <Step title="Navigate to Settings">
    Log into your CodeThreat dashboard and go to **Organization Settings** → **API Keys**.
  </Step>

  <Step title="Generate New Key">
    Click **Generate API Key** and provide a descriptive name (e.g., "CI/CD Pipeline", "Development").
  </Step>

  <Step title="Copy and Store Securely">
    Copy the generated API key immediately. For security, it won't be shown again.
  </Step>

  <Step title="Configure Your Requests">
    Include the API key in the `X-API-Key` header of all API requests.
  </Step>
</Steps>

***

## Making Authenticated Requests

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

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://app.codethreat.com/api/v1/organizations' \
    --header 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

***

## Environment Variables

Store API keys as environment variables for security:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Rotate Regularly" icon="rotate">
    Rotate API keys every 90 days or when team members leave
  </Card>

  <Card title="Use Descriptive Names" icon="tag">
    Name keys by purpose: "Production CI/CD", "Staging Environment"
  </Card>

  <Card title="Scope Appropriately" icon="lock">
    Use the minimum required permissions for each key
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Track API key usage in your audit logs
  </Card>
</CardGroup>

***

## Validate Your API Key

Test your API key with the CLI validation endpoint:

```bash theme={null}
curl --request GET \
  --url 'https://app.codethreat.com/api/v1/cli/auth/validate' \
  --header 'X-API-Key: YOUR_API_KEY'
```

**Success Response:**

```json theme={null}
{
  "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"
  }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore API" icon="book" href="/api-reference/organizations">
    Browse available API endpoints
  </Card>

  <Card title="CI/CD Integration" icon="gears" href="/automation/ci-cd-integration">
    Integrate with your pipeline
  </Card>
</CardGroup>