Generating and Managing API Keys

API keys allow external systems (POS terminals, custom apps, integrations) to authenticate with Cockato's REST API. This guide covers creating, using, and managing API keys securely.

What Are API Keys Used For?

Cockato's API keys enable server-to-server communication for use cases such as:

Creating an API Key

Only users with the owner or admin role can generate API keys.

Steps:

1. Navigate to Settings → API Keys
2. Click Generate New Key
3. Enter a descriptive label (e.g., "POS Integration - Main Store")
4. Click Create

You will see a modal displaying your Secret Key (e.g., ck_live_123abc...). This is the only time the full key will be shown.

⚠️ Critical: Copy the secret key immediately and store it in a secure password manager or environment variable. If you lose it, you will need to generate a new key.

API Key Anatomy

Each Cockato API key follows this format:

ck_live_a3b7c1d9e2f4g5h6i7j8k9

The first 8 characters of the key are stored as a prefix for identification purposes (e.g., ck_live_a3b7).

Using Your API Key

Include your API key in the Authorization header when making requests to the Cockato API:

curl https://api.cockato.com/v1/customers \
  -H "Authorization: Bearer ck_live_a3b7c1d9e2f4g5h6i7j8k9"

💡 Tip: Use the Bearer token scheme for all API requests. Keys sent in query parameters or request bodies are rejected for security.

Managing Existing Keys

The API Keys page displays all active and inactive keys for your organization.

Revoking a Key

If a key is compromised or no longer needed:

1. Locate the key in the API Keys list
2. Click the ⋮ menu → Revoke
3. Confirm the action

Revoked keys are immediately deactivated. Any system using the revoked key will receive 401 Unauthorized errors on the next API call.

Rotating Keys (Best Practice)

Rotate your API keys periodically (every 6-12 months) to minimize security risk:

1. Generate a new API key
2. Update your external systems with the new key
3. Monitor the Last Used timestamp on the old key
4. Once the old key has been inactive for 48 hours, revoke it

Security Best Practices

• Never commit keys to version control. Use environment variables (process.env.COCKATO_API_KEY in Node.js).
• Restrict key access. Store keys in secure vaults (AWS Secrets Manager, 1Password).
• Monitor usage. Regularly review the "Last Used" timestamps to detect unauthorized activity.
• Use separate keys per integration. This allows you to revoke a single integration without disrupting others.

API Documentation

For detailed endpoint specifications, visit the API Docs section in the Cockato dashboard or contact support for OpenAPI / Postman collections.