API Keys

Understanding and managing API keys for Quotient

API keys are the primary authentication mechanism for accessing the Quotient API. This guide covers the different key types, their use cases, and how to set them up correctly.

Key Types

Quotient uses a two-tier API key system designed for different security contexts:

Public Keys (pk_*)

Public keys are designed for client-side applications where the key is exposed in browser code or mobile apps.

Characteristics:

• Prefix: pk_
• Length: 20-40 characters after prefix
• Safe to expose in client-side code
• Limited set of scopes supported
• Origin-restricted for security
• Cannot access sensitive operations

Allowed Endpoints:

• POST /api/v0/analytics - Track events
• POST /api/v0/audience/people - Upsert people
• POST /api/v0/audience/companies - Upsert companies
• POST /api/v0/audience/lists/:slug/people - Add people to a list
• DELETE /api/v0/audience/lists/:slug/people - Remove people from a list
• GET /api/v0/blog/* - Retrieve blogs, authors, and tags
• POST /api/v0/flow/:id/trigger - Trigger a programmatic flow
• GET /api/v0/whoami - Verify key configuration and get client context

Use Cases:

• Integrating signup forms with Quotient
• Centralizing client-side analytics
• Publishing blogs and content managed by Quotient on your website
• Triggering flows from your frontend

Private Keys (sk_*)

Private keys are for server-side applications where the key can be kept secret.

Characteristics:

• Prefix: sk_
• Length: 20-40 characters after prefix
• Must be kept secret
• Full support for all scopes
• IP address restrictions (coming soon)

Use Cases:

• Server-to-server integrations
• Backend services
• Data imports/exports
• Administrative operations

Security Warning: Never expose private keys in client-side code, version control, or public repositories.

Key Security Features

Origin Restrictions (Public Keys)

Public keys can be restricted to specific origins to prevent unauthorized use if the key is stolen.

How it works:

1. The API checks the Origin header of incoming requests
2. Compares against the allowed origins list
3. Rejects requests from unauthorized origins

Origin formats supported:

• Wildcard: * - Allow any origin (not recommended for production)
• Domain: example.com - Matches example.com and all subdomains
• Subdomain: app.example.com - Matches only this specific subdomain
• With protocol: https://app.example.com - Matches exact protocol and domain
• With port: localhost:3000 - Matches localhost on specific port

Examples:

✅ Valid origins:
- example.com
- app.example.com
- subdomain.example.com
- localhost:3000
- https://app.example.com:8080

❌ Invalid origins:
- http://  (protocol only)
- :3000    (port only)
- .com     (TLD only)

Matching rules:

• example.com matches:
  • https://example.com
  • https://www.example.com
  • https://app.example.com
• app.example.com matches only:
  • https://app.example.com
  • http://app.example.com

Scopes

API keys support granular permission scopes. When creating a key, you can assign one or more scopes to limit what it can access. The default is ALL.

Scope	Description
ALL	Full access to all endpoints
ANALYTICS_READ	Read analytics data
ANALYTICS_WRITE	Track events
AUDIENCE_READ	Read people, companies, and lists
AUDIENCE_WRITE	Create/update people, companies, and list membership
BLOG_READ	Read blogs, authors, and tags
BLOG_WRITE	Create/update blog content
FLOW_TRIGGER	Trigger programmatic flows
MEMORY_READ	Read memory documents
MEMORY_WRITE	Create/update memory documents

Key Expiration

Keys can have optional expiration dates for temporary access:

• Useful for trials or time-limited integrations
• Automatically rejected after expiration
• No impact on existing data

Usage Tracking

Each key tracks:

• Last used: Timestamp of most recent API call
• Created at: When the key was generated
• Created by: User who created the key

Creating API Keys

Via Dashboard

For now, you can only create public keys via the dashboard.

1. Navigate to Settings → Developers in your business dashboard
2. Click "Create API Key"
3. Configure the key:
   • Name: Descriptive identifier (e.g., "Production Web App")
   • Description: Optional details about usage
   • Allowed Origins: Domains that can use this key

Best Practices for Key Creation

Security Recommendations

1. Principle of Least Privilege

   • Create separate keys for different environments
   • Use the most restrictive origin settings possible

2. Origin Restrictions

   • Never use * (wildcard) in production
   • Be specific with subdomains
   • Include ports when necessary

Using API Keys

In Requests

Include the API key in the Authorization header:

curl -X POST https://api.quotient.com/api/v0/analytics \
  -H "Authorization: Bearer pk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"eventType": "pageView"}'

With SDKs

// JavaScript SDK
const quotient = await QuotientClient.init({
  apiKey: 'pk_test_1234567890abcdef'
});

// React SDK
<QuotientProvider clientOptions={{ 
  apiKey: 'pk_test_1234567890abcdef' 
}}>

Next Steps