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

# Authentication

> Learn how to authenticate with the CardClan Integration API using Bearer tokens

## Overview

The CardClan Integration API uses **Bearer token authentication** for secure access to all endpoints. You'll need to generate an integration key from your CardClan dashboard and include it in the Authorization header of your API requests.

## Generating Your Integration Key

<Steps>
  <Step title="Access Your CardClan Dashboard">
    Log in to your CardClan account and navigate to any card you want to use for integration
  </Step>

  <Step title="Generate Key">
    Click "Generate Integration Key" if you don't already have one
  </Step>

  <Step title="Secure Storage">
    Copy and securely store your integration key - you won't be able to see it again
  </Step>
</Steps>

<Warning>
  Your integration key is sensitive information. Keep it secure and never share it publicly or commit it to version control.
</Warning>

## Using Your Integration Key

Include your integration key in the `Authorization` header of every API request:

```bash theme={null}
curl -X GET "https://api.cardclan.com/api/integration/auth/validate" \
  -H "Authorization: Bearer YOUR_INTEGRATION_KEY"
```

## Key Format

CardClan integration keys are UUID-based tokens:

* **Format**: `550e8400-e29b-41d4-a716-446655440000`
* **Length**: 36 characters including hyphens
* **Case**: Case-sensitive

## Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant CardClan API
    
    Client->>CardClan API: Request with Bearer token
    CardClan API->>CardClan API: Validate token against user database
    alt Valid Token
        CardClan API->>Client: 200 OK + Response data
    else Invalid Token
        CardClan API->>Client: 404 Not Found - Invalid token
    end
```

## Testing Authentication

You can test your authentication setup using the validation endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cardclan.com/api/integration/auth/validate" \
    -H "Authorization: Bearer YOUR_INTEGRATION_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cardclan.com/api/integration/auth/validate', {
    headers: {
      'Authorization': 'Bearer YOUR_INTEGRATION_KEY'
    }
  });

  const result = await response.json();
  console.log(result);
  ```

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

  headers = {
      'Authorization': 'Bearer YOUR_INTEGRATION_KEY'
  }

  response = requests.get(
      'https://api.cardclan.com/api/integration/auth/validate',
      headers=headers
  )

  print(response.json())
  ```
</CodeGroup>

**Successful Response:**

```json theme={null}
{
  "success": true,
  "message": "Bearer token authentication successful",
  "user_id": "60f7b2b5b8f4a20015a4f5a3"
}
```

## Common Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized - Missing Authorization Header">
    **Error**: `Authorization header with Bearer token required`

    **Solution**: Ensure you're including the `Authorization: Bearer YOUR_KEY` header in your request.
  </Accordion>

  <Accordion title="401 Unauthorized - Empty Bearer Token">
    **Error**: `Bearer token is empty`

    **Solution**: Check that your token value is not empty or null after "Bearer ".
  </Accordion>

  <Accordion title="404 Not Found - Invalid Token">
    **Error**: `Invalid bearer token - user not found`

    **Solution**: Verify your integration key is correct and hasn't been regenerated. Generate a new key if needed.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you have authentication set up:

1. [Learn about merge tags](/merge-tags) for personalization
2. [Explore the API reference](/api-reference/integration/overview) for detailed endpoint documentation