Authentication

Complete guide to API authentication with Cutly. Learn how to create, manage, and use API keys securely.

Overview

The Cutly API uses API key authentication to provide secure, programmatic access to your account and resources. API keys are tenant-specific credentials that allow applications to interact with the Cutly platform on your behalf without requiring user credentials.

Security Features

• Bearer token authentication
• SHA-256 hashing for storage
• Granular permission system
• Automatic expiration support
• Rate limiting protection
• Activity logging and monitoring

Key Management

• Create multiple API keys
• Activate/deactivate keys
• Set custom permissions
• Track usage per key
• Prefix-based identification
• Secure key rotation

Important Security Note

API keys provide full access to your tenant's resources. Only users with Owner or Admin roles can create and manage API keys. Always store them securely and never share them publicly.

API Key Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token authentication scheme. The API validates each request by verifying the key's hash, checking its active status, and confirming it hasn't expired.

Authentication Flow

Client sends request with API key

The API key is included in the Authorization header as a Bearer token

Server validates the key

The server hashes the key using SHA-256 and looks it up in the database

Status and expiration check

Verifies the key is active (is_active = true) and hasn't expired

Permission verification

Checks if the key has the required permissions for the requested operation

Request processing and logging

If all checks pass, the request is processed and usage is logged

Header Format

Required Authorization Header

Authorization: Bearer cutly_1234567890abcdef1234567890abcdef

• The header name is Authorization
• The value must start with Bearer followed by a space
• The API key follows the Bearer prefix
• API keys are case-sensitive and must match exactly

Creating API Keys

Only users with Owner or Admin roles can create API keys. The creation process generates a secure 64-character key that is shown only once for security reasons.

Prerequisites

Required Permissions

Owner- Full access to create and manage all API keys

Admin- Can create and manage API keys for the organization

Member- Cannot create or manage API keys

Step-by-Step Guide

Navigate to APIs Section

From your dashboard, go to the APIs section in the sidebar menu.

Click "Create New API Key"

Click the "Create New API Key" button to open the creation dialog.

Enter Key Name and Permissions

Provide a descriptive name and select the permissions for this key:

• Name: e.g., "Production Integration", "Development Key"
• Permissions: Select from granular permissions like links:read, links:write, etc.
• Expiration: Optionally set an expiration date

Copy the Generated Key

Critical: The API key is displayed only once! Copy it immediately and store it in a secure location.

The key will never be shown again. If lost, you must create a new key.

API Key Structure

Key Format

# Example API Key (format: cutly_ + 32 hex characters)

cutly_1234567890abcdef1234567890abcdef

• Prefix: All keys start with cutly_
• Length: 64 total characters for maximum security
• Storage: Only the SHA-256 hash is stored in the database
• Display: Only the first 12 characters (prefix) are shown in the UI

Using API Keys

Include your API key in all requests to authenticate with the Cutly API. Here are examples in various programming languages.

Code Examples

cURL

curl -X GET "https://cutly.xyz/api/v1/links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript (fetch)

fetch('https://cutly.xyz/api/v1/links', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://cutly.xyz/api/v1/links',
    headers=headers
)
data = response.json()

Node.js (axios)

const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

axios.get('https://cutly.xyz/api/v1/links', config)
  .then(response => console.log(response.data));

Environment Variables

Recommended: Store Keys as Environment Variables

Create a .env file:

# .env
CUTLY_API_KEY=cutly_your_api_key_here
CUTLY_BASE_URL=https://cutly.xyz/api/v1

Access in your code:

const apiKey = process.env.CUTLY_API_KEY;
const baseUrl = process.env.CUTLY_BASE_URL;

Permissions & Roles

API keys use a granular permission system that controls access to specific resources and operations. Only users with appropriate roles can create keys with certain permissions.

Permission Types

Read Permissions

• links:read - View short links
• qr_codes:read - View QR codes
• analytics:read - View analytics data
• pages:read - View custom pages
• team_members:read - View team members
• custom_domain:read - View domains

Write Permissions

• links:write - Create/update/delete links
• qr_codes:write - Manage QR codes
• pages:write - Manage custom pages
• team_members:write - Manage team
• custom_domain:write - Manage domains
• api_keys:write - Manage API keys

Role-Based Access

Role	Can Create Keys	Default Permissions
Owner		Full access to all permissions
Admin		All except api_keys:write
Member		Cannot create API keys

Permission Enforcement

Each API endpoint checks the specific permissions required for the operation. A request will return a 403 Forbidden error if the API key lacks the necessary permissions.

Rate Limiting

API requests are rate limited to ensure fair usage and platform stability. Rate limits are applied per API key using Redis-based sliding window counters.

Rate Limit Tiers

Endpoint Type	Limit	Window
Read Operations	100 requests	per minute
Write Operations	50 requests	per minute
Analytics	200 requests	per minute
Public Redirects	60 requests	per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320600

• X-RateLimit-Limit: Maximum requests allowed per window
• X-RateLimit-Remaining: Requests left in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets

Rate Limit Exceeded

429 Too Many Requests

When you exceed the rate limit, the API returns a 429 status code with this response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 45
}

Best Practices:

• Monitor the rate limit headers in responses
• Implement exponential backoff when hitting limits
• Respect the Retry-After header value
• Cache responses when possible to reduce API calls

Security Best Practices

Following security best practices is essential when working with API keys to protect your account and data from unauthorized access.

Storage & Handling

Never Commit Keys to Code

• Don't hardcode API keys in source files
• Use environment variables instead
• Add .env files to .gitignore
• Scan repositories for leaked keys

Secure Storage

• Use password managers or secret vaults
• Encrypt configuration files
• Implement proper access controls
• Never store in browser localStorage

Operational Security

Key Rotation

• Rotate keys every 90 days minimum
• Create new keys before deleting old ones
• Update all integrations simultaneously
• Document rotation procedures

Monitoring

• Monitor API usage patterns
• Set up alerts for unusual activity
• Review API logs regularly
• Track which keys are being used

Additional Security Measures

• Principle of Least Privilege: Only grant the minimum permissions needed
• Separate Keys for Environments: Use different keys for dev, staging, and production
• Set Expiration Dates: Configure keys to expire automatically
• Revoke Immediately: Deactivate keys immediately if compromised
• Use HTTPS Only: Never send API keys over unencrypted connections
• Backend Only: Never use API keys in client-side JavaScript

Troubleshooting

Common issues and solutions when working with API authentication. Check these before reaching out for support.

401 Unauthorized

Common causes:

• Missing Authorization header
• Incorrect Bearer prefix format
• Invalid or expired API key
• Key has been deactivated
• Typos or extra whitespace in key

Solutions:

• Verify header: Authorization: Bearer KEY
• Check key status in dashboard
• Confirm key hasn't expired
• Generate a new key if necessary

403 Forbidden

Common causes:

• Insufficient permissions for operation
• Wrong permission scope on key
• Account limits exceeded
• Feature not in your plan

Solutions:

• Check required permissions for endpoint
• Verify key has correct scopes
• Review account plan limits
• Contact support if permissions seem correct

429 Rate Limited

Common causes:

• Exceeded requests per minute
• Too many concurrent requests
• Burst traffic without throttling

Solutions:

• Wait for rate limit window to reset
• Implement exponential backoff
• Check X-RateLimit-Reset header
• Reduce request frequency

Testing Your API Key

Quick test to verify your API key works:

curl -H "Authorization: Bearer YOUR_KEY" \
  https://cutly.xyz/api/v1/links?limit=1

Expected: JSON response with your links data

Need Help?

If you encounter issues not covered in this guide or need additional assistance, we're here to help.

Getting Help

Email Support

Get detailed help via email

support@cutly.com

Response within 24 hours

Live Chat

Instant help from our Chatbot

Available 24/7

Pro+ users only

Documentation

Comprehensive guides and examples

Always Available

Self-service help

Can't find what you're looking for? Contact our support team

On this page