Skip to main content

​
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

1

Access Your CardClan Dashboard

Log in to your CardClan account and navigate to any card you want to use for integration
2

Generate Key

Click “Generate Integration Key” if you don’t already have one
3

Secure Storage

Copy and securely store your integration key - you won’t be able to see it again
Your integration key is sensitive information. Keep it secure and never share it publicly or commit it to version control.

​
Using Your Integration Key

Include your integration key in the Authorization header of every API request: 
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

​
Testing Authentication

You can test your authentication setup using the validation endpoint: 
curl -X GET "https://api.cardclan.com/api/integration/auth/validate" \
  -H "Authorization: Bearer YOUR_INTEGRATION_KEY"
Successful Response: 
{
  "success": true,
  "message": "Bearer token authentication successful",
  "user_id": "60f7b2b5b8f4a20015a4f5a3"
}

​
Common Authentication Errors

Error: Authorization header with Bearer token requiredSolution: Ensure you’re including the Authorization: Bearer YOUR_KEY header in your request.
Error: Bearer token is emptySolution: Check that your token value is not empty or null after “Bearer ”.
Error: Invalid bearer token - user not foundSolution: Verify your integration key is correct and hasn’t been regenerated. Generate a new key if needed.

​
Next Steps

Now that you have authentication set up:
  1. Learn about merge tags for personalization
  2. Explore the API reference for detailed endpoint documentation