API Keys

API keys allow server-to-server communication with Cueflow. Use them to manage contacts and track events from your backend.

When to Use API Keys

Use the server-side API when you need to:

• Sync contacts from your database

• Track events from webhooks

• Update contact properties server-side

• Integrate with backend processes

For client-side tracking, use the embed script instead.

Managing API Keys

Access API Settings

1. Go to Settings in the sidebar

2. Select API Keys

Create an API Key

1. Click Create API Key

2. Enter a name (e.g., "Production Server", "Webhook Handler")

3. Click Create

4. Copy the key immediately - it won't be shown again

API keys are shown only once. Copy and store it securely before closing the dialog.

Key Format

API keys look like:

sk_a1b2c3d4e5f6...

The sk_ prefix indicates a secret key.

View Existing Keys

The API Keys page shows:

• Key name

• Key prefix (first 12 characters)

• Created date

• Last used date

Delete a Key

1. Find the key in the list

2. Click Delete

3. Confirm deletion

Deleting a key immediately invalidates it. Any systems using that key will stop working.

Using the API

Authentication

Include your API key in the Authorization header:

curl -X POST https://app.cueflow.so/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API Endpoints

Contacts

Create or update a contact:

POST /api/v1/contacts

{
  "externalId": "user-123",
  "email": "[email protected]",
  "name": "Jane Smith",
  "plan": "pro",
  "attributes": {
    "company": "Acme Inc",
    "teamSize": 50
  }
}

Get a contact:

GET /api/v1/contacts/user-123

Update a contact:

PATCH /api/v1/contacts/user-123

{
  "plan": "enterprise",
  "attributes": {
    "teamSize": 100
  }
}

Delete a contact:

DELETE /api/v1/contacts/user-123

Events

Track an event:

POST /api/v1/events

{
  "externalId": "user-123",
  "eventKey": "subscription_renewed",
  "properties": {
    "plan": "pro",
    "amount": 99
  }
}

Response Format

Successful responses return JSON:

{
  "success": true,
  "contact": {
    "id": "clx...",
    "externalId": "user-123",
    "email": "[email protected]",
    ...
  }
}

Error responses:

{
  "error": "Not found",
  "message": "Contact not found"
}

Rate Limiting

API requests are rate limited:

• 100 requests per minute per API key

• Rate limit headers included in responses:

  • X-RateLimit-Limit: Request limit

  • X-RateLimit-Remaining: Remaining requests

  • X-RateLimit-Reset: Reset timestamp

Use Cases

Sync Contacts on Signup

When a user signs up in your app:

// Your signup handler
async function handleSignup(user) {
  // Create user in your database
  await db.createUser(user);

  // Sync to Cueflow
  await fetch('https://app.cueflow.so/api/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      externalId: user.id,
      email: user.email,
      name: user.name,
      signedUpAt: new Date().toISOString()
    })
  });
}

Track Webhook Events

When receiving a Stripe webhook:

// Stripe webhook handler
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;

  if (event.type === 'customer.subscription.updated') {
    const subscription = event.data.object;

    // Update contact in Cueflow
    await fetch(`https://app.cueflow.so/api/v1/contacts/${subscription.metadata.userId}`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        plan: subscription.items.data[0].price.lookup_key
      })
    });

    // Track the event
    await fetch('https://app.cueflow.so/api/v1/events', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        externalId: subscription.metadata.userId,
        eventKey: 'subscription_updated',
        properties: {
          plan: subscription.items.data[0].price.lookup_key
        }
      })
    });
  }

  res.json({ received: true });
});

Batch Updates

Update multiple contacts in a loop:

async function syncAllContacts() {
  const users = await db.getAllUsers();

  for (const user of users) {
    await fetch('https://app.cueflow.so/api/v1/contacts', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        externalId: user.id,
        email: user.email,
        name: user.name,
        plan: user.subscription.plan
      })
    });

    // Respect rate limits
    await sleep(100);
  }
}

Security Best Practices

Keep Keys Secret

• Never commit keys to version control

• Use environment variables

• Don't expose in client-side code

Use Separate Keys

• Create different keys for different environments

• Name them clearly (Production, Staging, Development)

• Rotate keys periodically

Monitor Usage

• Check "Last Used" dates

• Delete unused keys

• Watch for unexpected activity

Rotate Keys

1. Create a new key

2. Update your systems to use the new key

3. Delete the old key