Authentication

Secure your API requests with API key authentication

API keys

ClickyID uses API keys to authenticate requests. API keys are unique to your team and can be configured with specific scopes and rate limits.

Security Note: Keep your API keys secure and never expose them in client-side code. Always use API keys on your server or in secure environments.

Creating API keys

Navigate to your team dashboard and click “API keys”
Click “Create API key” and give it a descriptive name
Select the scopes you need (e.g., validate:offers, validate:target-groups) and set rate limits for your key
Copy and securely store your API key - it will only be shown once

Using API keys

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

Authorization: Bearer ck_live_your_api_key_here

Example Request

Loading syntax highlighting...

API key Format

ClickyID API keys follow a specific format to help identify their type and environment:

Live Keys

ck_live_1234567890abcdef1234567890abcdef12345678

Used for production environments. These keys have access to real data and rate limits apply.

Test Keys (Coming Soon)

ck_test_1234567890abcdef1234567890abcdef12345678

Used for development and testing. These keys have limited functionality and higher rate limits.

API key Scopes

API keys can be configured with specific scopes to limit access to certain endpoints:

Target Group Validation validate:target-groups

Access to validate emails against target groups and list available target groups

Endpoints: /validate/target-group, /target-groups

Offer Validation validate:offers

Access to validate emails against offers and list available offers

Endpoints: /validate/offer, /offers

Note

The bulk validation endpoint (/validate/bulk) requires the appropriate scope based on what you're validating against (target groups or offers).

Rate Limiting

API keys can be configured with custom rate limits to control usage:

Default Limits

1,000 requests per hour per API key
100 emails maximum per bulk validation request
Rate limits reset every hour

Rate Limit Headers

All API responses include rate limiting information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When you exceed your rate limit, the API will return a 429 status code:

Loading syntax highlighting...

Security Best Practices

Store API keys securely

Use environment variables or secure key management systems

Use HTTPS only

Always make API requests over HTTPS to protect your keys in transit

Limit key scopes

Only grant the minimum required permissions for each API key

Rotate keys regularly

Generate new API keys periodically and revoke old ones

Never expose keys in client-side code

API keys should only be used on your server or in secure environments

Don't commit keys to version control

Use .env files and add them to your .gitignore

Monitoring API Usage

Track your API key usage through the team dashboard:

Usage Analytics

View request counts, success rates, and response times

Real-time Monitoring

Track current rate limit usage and remaining quota

Request Logs

View detailed logs of API requests and responses

Next Steps

Quick Start

Get started with the ClickyID API in just a few minutes using your API key.

Get Started

API Reference

Complete reference for all ClickyID API endpoints and authentication requirements.

View API Reference

Code Examples

Ready-to-use code examples showing how to authenticate API requests.

Browse Examples

Security Guide

Learn about security best practices and implementation guides.

Read Guides