User Access Guide - customers.dev

Complete guide to authentication, authorization, and accessing the customers.dev platform.

Table of Contents

1. Overview
2. Authentication
3. Organizations & Teams
4. Role-Based Access Control (RBAC)
5. API Access
6. Getting Started
7. Common Workflows

Overview

customers.dev uses a secure, multi-tenant architecture where:

• Authentication is handled by Clerk (OAuth, email/password, SSO)
• Organizations provide workspace isolation for teams
• Role-Based Access Control (RBAC) ensures proper permissions
• API Keys enable programmatic access to your data

Authentication

User Registration & Login

Supported Methods:

• Email & Password
• Google OAuth
• GitHub OAuth
• Microsoft OAuth
• SAML SSO (Enterprise plans)
• Magic Links

Sign Up Flow:

1. Visit https://customers.dev/sign-up
2. Choose authentication method
3. Complete verification (email confirmation)
4. Create or join an organization

Sign In Flow:

1. Visit https://customers.dev/sign-in
2. Enter credentials or use OAuth
3. Access your organization dashboard

Session Management

• Session Duration: 7 days (configurable)
• Auto-Refresh: Sessions refresh automatically while active
• Multi-Device: Access from multiple devices simultaneously
• Security: Sessions invalidate on password change

Organizations & Teams

Organization Structure

Every user must belong to at least one organization. Organizations provide:

• Data Isolation: Your customers, contacts, and lists are private to your org
• Team Collaboration: Invite team members with specific roles
• Billing Scope: Subscriptions and usage limits are per-organization
• API Keys: Each organization has its own API keys

Creating an Organization

First-Time Users:

• Automatically prompted to create an organization during signup
• Required fields: Organization name
• Default role: Owner

Existing Users:

1. Navigate to organization switcher (top-left dropdown)
2. Click "Create New Organization"
3. Enter organization name
4. Confirm creation

Organization Plans

Switching Organizations

Users can belong to multiple organizations:

1. Click organization name (top-left)
2. Select from dropdown list
3. Dashboard updates to show selected org's data

Role-Based Access Control (RBAC)

Role Hierarchy

customers.dev uses a hierarchical role system where higher roles inherit lower role permissions:

Permission Matrix

Managing Team Members

Inviting Members (Admin/Owner only):

1. Navigate to Settings → Team Members
2. Click "Invite Member"
3. Enter email address
4. Select role: Viewer, Member, or Admin
5. Send invitation

Accepting Invitations:

1. Check email for invitation link
2. Click "Accept Invitation"
3. Sign in or create account
4. Access organization immediately

Changing Member Roles (Admin/Owner only):

1. Navigate to Settings → Team Members
2. Find member in list
3. Click role dropdown
4. Select new role
5. Confirm change

Removing Members (Admin/Owner only):

1. Navigate to Settings → Team Members
2. Find member in list
3. Click "Remove" button
4. Confirm removal

Important Notes:

• Owners cannot be removed (must transfer ownership first)
• You cannot change your own role
• Removing a member immediately revokes access

API Access

Overview

Programmatic access to customers.dev requires API keys. API keys are scoped to your organization and have specific permissions.

Creating API Keys

Requirements:

• Admin or Owner role
• Navigate to Settings → API Keys

Creation Steps:

1. Click "Create API Key"
2. Enter descriptive name (e.g., "Production Server", "Analytics Pipeline")
3. Select permissions:
   • customers:read - Read customer data
   • customers:write - Create/update customers
   • contacts:read - Read contact data
   • contacts:write - Create/update contacts
   • lists:read - Read lists
   • lists:write - Create/update lists
4. Set rate limits (optional):
   • Requests per minute (default: 60)
   • Requests per hour (default: 1,000)
   • Requests per day (default: 10,000)
5. Set expiration (optional):
   • Never expires (default)
   • Custom expiration date
6. Click "Create"

Security Notice: ⚠️ The API key is shown ONLY ONCE. Copy and store it securely immediately.

API Key Format

sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• sk_ - Secret key prefix
• test_ / live_ - Environment indicator
• 32 random characters

Using API Keys

Authentication Header:

curl -H "Authorization: Bearer sk_test_xxxx..." \
  https://api.customers.dev/v1/customers

Base URL:

• Test: https://api.customers.dev/v1
• Production: https://api.customers.dev/v1

API Key Management

Viewing API Keys:

• Navigate to Settings → API Keys
• See list of all keys with:
  • Name
  • Key prefix (e.g., sk_test_xxxx...)
  • Permissions
  • Last used timestamp
  • Status (Active/Revoked/Expired)

Revoking API Keys:

1. Navigate to Settings → API Keys
2. Find key to revoke
3. Click "Revoke"
4. Confirm revocation
5. Key immediately stops working

Updating Permissions:

1. Navigate to Settings → API Keys
2. Find key to update
3. Click "Edit Permissions"
4. Toggle permissions
5. Save changes

Updating Rate Limits:

1. Navigate to Settings → API Keys
2. Find key to update
3. Click "Edit Rate Limits"
4. Adjust limits
5. Save changes

Rate Limiting

Limits:

• Per Minute: 60 requests (default)
• Per Hour: 1,000 requests (default)
• Per Day: 10,000 requests (default)

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Rate Limit Exceeded:

HTTP 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "limit": 60,
  "used": 60,
  "resetAt": 1640000000
}

Handling Rate Limits:

1. Implement exponential backoff
2. Cache responses when possible
3. Batch operations
4. Upgrade plan for higher limits

API Key Security Best Practices

✅ DO:

• Store keys in environment variables
• Use separate keys for development/production
• Rotate keys regularly (every 90 days)
• Use minimum required permissions
• Revoke unused keys immediately
• Monitor API key usage

❌ DON'T:

• Commit keys to version control
• Share keys between environments
• Use overly broad permissions
• Hardcode keys in application code
• Expose keys in client-side code
• Ignore usage anomalies

Getting Started

Step 1: Create Account

1. Visit https://customers.dev/sign-up
2. Choose authentication method
3. Verify email address
4. Complete profile

Step 2: Create Organization

1. Enter organization name
2. Select plan (Free to start)
3. Confirm creation
4. You're assigned Owner role

Step 3: Invite Team Members (Optional)

1. Navigate to Settings → Team Members
2. Invite colleagues with appropriate roles
3. They'll receive email invitations

Step 4: Add Your First Customer

Via Dashboard:

1. Click "Customers" in sidebar
2. Click "Add Customer"
3. Fill in details:
   • Company name (required)
   • Domain
   • Status (Lead/Customer/Churned)
   • Industry, size, etc.
4. Click "Save"

Via API:

curl -X POST https://api.customers.dev/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "acme.com",
    "status": "customer"
  }'

Step 5: Add Contacts

Via Dashboard:

1. Open customer profile
2. Click "Add Contact"
3. Fill in details:
   • First name, last name (required)
   • Email, phone
   • Title, LinkedIn
4. Mark as primary contact (optional)
5. Click "Save"

Via API:

curl -X POST https://api.customers.dev/v1/contacts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@acme.com",
    "isPrimaryContact": true
  }'

Step 6: Create Lists

Via Dashboard:

1. Click "Lists" in sidebar
2. Click "Create List"
3. Enter details:
   • Name (required)
   • Description
   • Type: Waitlist/Prospects/Newsletter/Custom
4. Click "Create"
5. Add customers/contacts to list

Common Workflows

Workflow 1: Onboarding a New Customer

1. Create customer record

   • Add company information
   • Set status to "lead"

2. Add primary contact

   • Create contact for main decision maker
   • Mark as primary contact

3. Add to relevant lists

   • Add to "Active Prospects" list
   • Add to industry-specific list

4. Track engagement

   • Update notes as communication happens
   • Move through sales stages

Workflow 2: Team Collaboration

1. Owner invites team members

   • Sales team: Member role (can edit)
   • Analytics team: Viewer role (read-only)
   • Sales managers: Admin role (full access)

2. Members access shared data

   • Everyone sees same customers/contacts
   • Edit permissions based on role

3. Admins manage API keys

   • Create keys for integrations
   • Monitor usage
   • Revoke when needed

Workflow 3: API Integration

1. Admin creates API key

   • Name: "CRM Sync"
   • Permissions: customers:read, customers:write, contacts:write
   • Rate limit: 100/minute

2. Store key securely

   export CUSTOMERS_API_KEY="sk_live_..."

3. Sync data

   import requests
   
   headers = {
       "Authorization": f"Bearer {os.environ['CUSTOMERS_API_KEY']}",
       "Content-Type": "application/json"
   }
   
   # Fetch customers
   response = requests.get(
       "https://api.customers.dev/v1/customers",
       headers=headers
   )
   customers = response.json()

4. Monitor usage

   • Check API key usage stats in dashboard
   • Set up alerts for rate limit approach

Workflow 4: Managing Customer Lists

1. Create segmented lists

   • "Enterprise Customers" (>1000 employees)
   • "At-Risk Customers" (low engagement)
   • "Expansion Opportunities" (growth potential)

2. Add customers to lists

   • Manually via dashboard
   • Bulk import via API
   • Automated via webhooks (future)

3. Use lists for campaigns

   • Export list for email campaigns
   • Track which lists convert best
   • Update list membership as status changes

Support & Resources

Documentation

• API Reference: https://docs.customers.dev/api
• Guides: https://docs.customers.dev/guides
• Changelog: https://docs.customers.dev/changelog

Support Channels

• Email: help@do.dev
• Contact Page: https://do.dev/contact
• Chat: Available in dashboard (Pro+ plans)

Security & Compliance

• Security Policy: https://customers.dev/security
• Privacy Policy: https://customers.dev/privacy
• Terms of Service: https://customers.dev/terms
• SOC 2 Compliance: Available for Enterprise customers

Emergency Contacts

• Security Issues: security@customers.dev
• Data Deletion Requests: privacy@customers.dev
• Billing Issues: billing@customers.dev

Appendix: Permission Details

READ Permissions

customers:read

• View customer details
• Search customers
• List customers
• Export customer data

contacts:read

• View contact details
• Search contacts
• List contacts
• Export contact data

lists:read

• View list details
• See list members
• Search lists

WRITE Permissions

customers:write

• Create customers
• Update customer information
• Add custom fields
• Update customer status

contacts:write

• Create contacts
• Update contact information
• Set primary contact
• Add contact notes

lists:write

• Create lists
• Update list details
• Add members to lists
• Remove members from lists
• Delete lists

Frequently Asked Questions

Authentication

Q: Can I use SSO with my organization? A: Yes, SAML SSO is available on Enterprise plans. Contact sales@customers.dev.

Q: How do I reset my password? A: Click "Forgot Password" on the login page and follow the email instructions.

Q: Can I require 2FA for my organization? A: Yes, Owners can enable 2FA requirement in Settings → Security.

Organizations

Q: Can I be in multiple organizations? A: Yes, you can be a member of unlimited organizations with the same email address.

Q: How do I transfer organization ownership? A: Navigate to Settings → Team, find the new owner, change their role to Owner. You'll be downgraded to Admin.

Q: What happens if I delete my organization? A: All data (customers, contacts, lists, API keys) is permanently deleted after 30 days.

Roles & Permissions

Q: Can Members see other team members? A: Yes, all roles can view the team member list, but only Admins/Owners can modify it.

Q: What's the difference between Admin and Owner? A: Owners have full control including billing, plan changes, and organization deletion. Admins can manage members and API keys but not organization settings.

Q: Can I customize permission levels? A: Custom roles are available on Enterprise plans. Contact sales@customers.dev.

API Keys

Q: How many API keys can I create? A: Unlimited API keys per organization.

Q: Can I regenerate a lost API key? A: No, API keys cannot be retrieved after creation. Revoke the old key and create a new one.

Q: Do API keys expire? A: Only if you set an expiration date during creation. Otherwise, they're valid until revoked.

Q: Can I use the same API key across multiple servers? A: Yes, but we recommend separate keys per integration for better security and monitoring.

Last Updated: January 2025 Version: 1.0.0