Skip to main content

​
Authentication

CHRT uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure and never share them in publicly accessible areas such as GitHub, client-side code, and so forth.

​
API Key Types

Public Keys

chrt_pk_[env][team][random]
  • Safe for browser/mobile use
  • Restricted by origin domains
  • Limited scopes available
  • Cannot access sensitive operations

Secret Keys

chrt_sk_[env][team][random]
  • Server-to-server communication only
  • Full access to all scopes
  • Can perform administrative operations
  • Must be kept confidential

​
Environments

All API keys are scoped to specific environments:
  • Test Environment (test): For development and testing
  • Live Environment (live): For production use
Test and live environments are completely separate. Data and operations in test mode will not affect your live data.

​
Authentication Methods

Include your API key in the Authorization header: 
curl https://nmixhdvexhgizmxlnhqi.supabase.co/functions/v1/validate-api-key \
  -H "Authorization: Bearer chrt_sk_test_..."

​
API Key Header

Alternatively, use the X-CHRT-API-Key header: 
curl https://nmixhdvexhgizmxlnhqi.supabase.co/functions/v1/validate-api-key \
  -H "X-CHRT-API-Key: chrt_pk_test_..."

​
Scopes

API keys can be restricted to specific scopes for security:
ScopeDescriptionKey Types
enc.tiles:readAccess chart tile imageryPublic, Secret
enc.mbtiles:downloadDownload offline chart packagesSecret only
interact.identify:readIdentify chart features by locationPublic, Secret
features.search:readSearch chart features and metadataPublic, Secret
query.spatial:readPerform spatial queries on chart dataPublic, Secret
keys.manageCreate and manage API keysSecret only
team.manageManage team members and settingsSecret only
Use wildcards for broader access: enc.*:read grants access to all ENC operations.

​
Restrictions

​
Domain Restrictions (Public Keys)

Public keys can be restricted to specific domains for security: 
{
  "domains": [
    "https://myapp.com",
    "https://*.myapp.com",
    "http://localhost:3000"
  ]
}

​
IP Allowlist

Restrict API key usage to specific IP addresses or CIDR blocks: 
{
  "ip_allowlist": [
    "192.168.1.0/24",
    "10.0.0.1",
    "2001:db8::/32"
  ]
}

​
Rate Limits

API keys have built-in rate limiting to prevent abuse:
  • Free Plan: 1,000 requests per month
  • Starter Plan: 10,000 requests per month
  • Pro Plan: 100,000 requests per month
  • Enterprise: Custom limits
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Security Best Practices

  • Generate separate keys for different environments
  • Use descriptive names to identify key purposes
  • Rotate keys regularly (we recommend every 90 days)
  • Revoke unused or compromised keys immediately
  • Always set domain restrictions for public keys
  • Use minimal required scopes
  • Monitor usage for unexpected patterns
  • Consider IP restrictions for known client IPs
  • Never expose secret keys in client-side code
  • Store in environment variables or secure vaults
  • Use HTTPS for all API requests
  • Implement proper error handling to avoid key leakage

​
Error Responses

Authentication errors return specific status codes:
StatusErrorDescription
401invalid_keyAPI key is malformed or doesn’t exist
403insufficient_scopeKey lacks required permissions
403domain_restrictedRequest origin not in allowlist
403ip_restrictedClient IP not in allowlist
429rate_limitedToo many requests
Example error response: 
{
  "error": {
    "type": "invalid_key",
    "message": "The provided API key is invalid or has been revoked.",
    "documentation_url": "https://docs.chrt.com/errors#invalid_key"
  }
}

​
Testing Authentication

Validate your API key setup: 
curl https://nmixhdvexhgizmxlnhqi.supabase.co/functions/v1/validate-api-key \
  -H "Authorization: Bearer chrt_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "chrt_sk_test_...",
    "requiredScopes": ["enc.tiles:read"]
  }'

​
Next Steps