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

# Authentication

> Corgea API Authentication and Token Verification

# Authentication

## Overview

The Corgea API uses API key authentication to secure access to all endpoints. Authentication is done via a custom header that must be included with every API request.

## Authentication Method

### API Key Header

All API requests require authentication using the `CORGEA-TOKEN` header:

* **Header Name**: `CORGEA-TOKEN`
* **Type**: API Key
* **Location**: Request Header
* **Required**: Yes (for all endpoints)

### Getting Your API Token

You can obtain your API token from the Corgea web application:

1. Log in to your Corgea account at [https://www.corgea.app](https://www.corgea.app)
2. Navigate to Settings → API Keys
3. Generate a new API key or copy an existing one
4. Store it securely - treat it like a password

<Warning>
  Never share your API token or commit it to version control. Use environment variables or secure secret management systems to store your tokens.
</Warning>

## Making Authenticated Requests

Include your API token in the `CORGEA-TOKEN` header with every request:

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://www.corgea.app/api/v1/verify" \
    -H "CORGEA-TOKEN: your_api_token_here"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "CORGEA-TOKEN": "your_api_token_here"
  }

  response = requests.get(
      "https://www.corgea.app/api/v1/verify",
      headers=headers
  )
  ```

  ```javascript JavaScript theme={null}
  const headers = {
    'CORGEA-TOKEN': 'your_api_token_here'
  };

  fetch('https://www.corgea.app/api/v1/verify', {
    method: 'GET',
    headers: headers
  })
    .then(response => response.json())
    .then(data => console.log(data));
  ```
</RequestExample>

## Verify Token

### Endpoint

Verify the validity of your API token and optionally retrieve user information.

* **URL**: `https://www.corgea.app/api/v1/verify`
* **Method**: `GET`
* **Authentication**: Required (CORGEA-TOKEN header)

### Query Parameters

| Name       | Type    | Required | Default | Description                                     |
| ---------- | ------- | -------- | ------- | ----------------------------------------------- |
| user\_info | boolean | No       | false   | Whether to include user information in response |

### Request Examples

<RequestExample>
  ```bash Basic Verification theme={null}
  curl -X GET "https://www.corgea.app/api/v1/verify" \
    -H "CORGEA-TOKEN: your_api_token_here"
  ```

  ```bash With User Info theme={null}
  curl -X GET "https://www.corgea.app/api/v1/verify?user_info=true" \
    -H "CORGEA-TOKEN: your_api_token_here"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "CORGEA-TOKEN": "your_api_token_here"
  }

  # Basic verification
  response = requests.get(
      "https://www.corgea.app/api/v1/verify",
      headers=headers
  )

  # With user info
  response = requests.get(
      "https://www.corgea.app/api/v1/verify",
      headers=headers,
      params={"user_info": True}
  )
  ```
</RequestExample>

### Response Examples

<ResponseExample>
  ```json Basic Response theme={null}
  {
    "status": "ok"
  }
  ```

  ```json With User Info theme={null}
  {
    "status": "ok",
    "user": {
      "id": 12345,
      "email": "user@example.com",
      "name": "John Doe",
      "company": {
        "id": 67890,
        "name": "Acme Corporation"
      }
    }
  }
  ```

  ```json Invalid Token theme={null}
  {
    "status": "error"
  }
  ```
</ResponseExample>

### Response Codes

| Status Code | Description                             |
| ----------- | --------------------------------------- |
| 200         | Token is valid                          |
| 401         | Invalid or missing authentication token |

## Common Authentication Errors

### Missing Token

If you don't include the `CORGEA-TOKEN` header, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "status": "error"
}
```

### Invalid Token

If your token is invalid or expired, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "status": "error"
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Secure Storage" icon="lock">
    Store API tokens in environment variables or secure secret management systems, never in code.
  </Card>

  <Card title="Token Rotation" icon="rotate">
    Regularly rotate your API tokens to maintain security.
  </Card>

  <Card title="Least Privilege" icon="shield-halved">
    Create separate tokens for different applications or environments.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly review API token usage and revoke unused tokens.
  </Card>
</CardGroup>

## Testing Your Token

Use the verify endpoint to test your token before making other API calls:

```bash theme={null}
curl -X GET "https://www.corgea.app/api/v1/verify?user_info=true" \
  -H "CORGEA-TOKEN: your_api_token_here"
```

If successful, you'll see your user information, confirming that:

* ✅ Your token is valid
* ✅ Your token is properly formatted in the header
* ✅ You can proceed with other API requests