Skip to main content

​
API Keys Overview

API keys are the foundation of CHRT’s authentication system. They grant access to specific features and operations while maintaining security through scopes, restrictions, and rate limits.

​
Key Architecture

CHRT uses a dual-key system designed for both security and developer experience:

Public Keys

chrt_pk_[env][team][random]
  • Browser and mobile safe
  • Origin domain restrictions
  • Limited to read-only scopes
  • CORS preflight support

Secret Keys

chrt_sk_[env][team][random]
  • Server-to-server only
  • Full administrative access
  • One-time reveal security
  • IP whitelist support

​
Key Lifecycle

Understanding the complete lifecycle helps you manage keys effectively:

​
States Explained

  • Active: Key is operational and can authenticate requests
  • Transition: During regeneration, both old and new keys work
  • Paused: Temporarily disabled but can be resumed
  • Revoked: Permanently disabled and cannot be restored

​
Security Model

​
Scope-Based Permissions

Every API key has specific scopes that determine what operations it can perform:
Scope CategoryDescriptionExample Scopes
ENC ChartsElectronic Navigational Chart accessenc.tiles:read, enc.mbtiles:download
InteractionsChart feature identificationinteract.identify:read
FeaturesChart metadata and searchfeatures.search:read
QueriesSpatial and attribute queriesquery.spatial:read
ManagementKey and team administrationkeys.manage, team.manage

​
Restriction Types

Enhance security with multiple restriction layers:
Control which websites can use your public keys:
{
  "domains": [
    "https://myapp.com",           // Exact match
    "https://*.myapp.com",         // Wildcard subdomains
    "http://localhost:3000"        // Development
  ]
}
Restrict usage to specific IP addresses or ranges:
{
  "ip_whitelist": [
    "192.168.1.1",               // Single IP
    "192.168.1.0/24",            // IPv4 CIDR
    "2001:db8::/32"              // IPv6 CIDR
  ]
}
Set automatic expiration for temporary access:
{
  "expires_at": "2024-12-31T23:59:59Z"
}

​
Rate Limiting

All API keys include built-in rate limiting to prevent abuse and ensure fair usage:

​
Rate Limit Tiers

PlanRequests/HourBurst LimitOverage
Free1,000100Blocked
Starter10,000500Blocked
Pro100,0002,000$0.01/req
EnterpriseCustomCustomCustom

​
Rate Limit Headers

Every API response includes rate limit information: 
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 3600

​
Usage Analytics

Track key usage with comprehensive analytics:

Request Metrics

  • Total requests
  • Success/error rates
  • Response times
  • Geographic distribution

Feature Usage

  • Tiles served
  • Features identified
  • Queries executed
  • Bytes transferred

Security Events

  • Failed authentications
  • Domain violations
  • IP restrictions
  • Rate limit hits

​
Best Practices

1

Principle of Least Privilege

Grant only the minimum scopes required for each use case
2

Environment Separation

Use separate keys for development, staging, and production
3

Regular Rotation

Rotate keys every 90 days or after security incidents
4

Monitor Usage

Set up alerts for unusual patterns or rate limit approaches
5

Secure Storage

Store secret keys in environment variables or secure vaults

​
Key Naming Convention

Use descriptive names that indicate purpose and environment: 
✅ Good Examples:
- "Production Web App - Public"
- "Backend API Server - Live"
- "Mobile App Development - Test"
- "Analytics Dashboard - Read Only"

❌ Poor Examples:
- "Key 1"
- "Test"
- "My Key"
- "Backup"

​
Integration Examples

​
Frontend (Public Key)

// Initialize with public key
const chrt = new CHRT({
  publicKey: 'chrt_pk_live_myteam_...',
  origin: window.location.origin
});

// Fetch chart tiles
const tiles = await chrt.charts.tiles({
  z: 12,
  x: 1024,
  y: 1024
});

​
Backend (Secret Key)

// Initialize with secret key
const chrt = new CHRT({
  secretKey: process.env.CHRT_SECRET_KEY,
  environment: 'live'
});

// Create new API keys
const newKey = await chrt.keys.create({
  name: 'Customer Portal Key',
  type: 'pk',
  scopes: ['enc.tiles:read']
});

​
Next Steps

Create Your First Key

Walk through creating and configuring API keys

Understand Scopes

Learn about available permissions and scope patterns

Set Up Restrictions

Configure domain and IP restrictions for security

Monitor Usage

Set up analytics and alerting for your keys