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 originating from your website
• POST /api/v0/people - Upsert people you gather from your website
• GET /api/v0/whoami - Verify key configuration and get client context

Use Cases:

• Integrating signup forms with Quotient
• Centralizing client side analytics
• (COMING SOON) Publishing your blogs and content managed by Quotient on your website

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 (Coming Soon)

API keys will support granular permission scopes:

• ALL - Full access (current default)

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' 
}}>

Environment Variables

Store keys in environment variables:

# .env.local
NEXT_PUBLIC_QUOTIENT_API_KEY=pk_1234567890abcdef
QUOTIENT_PRIVATE_KEY=sk_1234567890abcdef  # Server-side only

Framework examples:

// Next.js (client-side)
const apiKey = process.env.NEXT_PUBLIC_QUOTIENT_API_KEY;

// Node.js (server-side)
const apiKey = process.env.QUOTIENT_PRIVATE_KEY;

// Vite/React
const apiKey = import.meta.env.VITE_QUOTIENT_API_KEY;

Managing API Keys

Viewing Keys

1. Go to Settings → Developers
2. View all active keys with:
   • Name and description
   • Allowed origins
   • Last used timestamp

Troubleshooting

Common Issues

"Invalid API key"

• Verify the key hasn't been archived
• Check you're using the correct key type
• Ensure no extra spaces or characters

"Origin not allowed"

• Check the Origin header matches allowed origins
• Remember protocol matters (http vs https)
• Subdomain must match exactly

"Missing scopes"

• Verify the operation is allowed for your key type
• Public keys have limited endpoint access
• Check the specific error message

Debugging Tools

Use the whoami endpoint to debug:

const info = await quotient.auth.whoami({});
console.log({
  businessId: info.businessId,
  keyType: info.keyType,
  origin: info.origin,
  allowedOrigins: info.allowedOrigins
});

Best Practices Summary

Do's ✅

• Use environment variables for keys
• Implement key rotation
• Use specific origin restrictions
• Create separate keys per environment
• Monitor key usage
• Use public keys for client-side only

Don'ts ❌

• Hard-code keys in source code
• Commit keys to version control
• Use wildcard origins in production
• Share keys between environments
• Use private keys client-side
• Ignore key compromise

Next Steps