Skip to main content

​
API Key Authentication

API keys are used for all programmatic access to the OMOPHub API. They provide:
  • Long-lived access: No expiration for continuous integration
  • Granular permissions: Control access to specific resources
  • Usage tracking: Monitor API consumption per key
  • Multiple keys: Create keys for different environments

​
API Key Types

Individual developer keys for personal projects
  • Tied to your user account
  • Inherit your account permissions
  • Usage counts toward personal quota
  • Can be revoked anytime
Shared keys for team collaboration (Coming Soon)
  • Associated with team/organization
  • Shared usage limits
  • Role-based access control
  • Audit logging per team member

​
Authentication Flow

​
API Authentication Flow

​
Security Best Practices

API keys provide full access to your account’s resources. Treat them like passwords and never expose them in client-side code or public repositories.

​
API Key Security

  1. Environment Variables: Store keys in environment variables 
    export OMOPHUB_API_KEY="oh_xxxxxxxxx"
  2. Key Rotation: Regularly rotate keys (every 90 days recommended)
  3. Minimal Permissions: Create keys with only necessary permissions
  4. Separate Environments: Use different keys for dev/staging/production
  5. Monitor Usage: Check API key usage regularly for anomalies

​
Authentication Headers

​
API Key Authentication

Include your API key in the Authorization header: 
curl -H "Authorization: Bearer oh_xxxxxxxxx" \
  https://api.omophub.com/v1/vocabularies

​
Troubleshooting

  • Check the key hasn’t been revoked
  • Verify you’re using the correct environment
  • Confirm proper Authorization header format
  • Check X-RateLimit headers in responses
  • Implement exponential backoff
  • Consider upgrading your plan
  • Use caching to reduce requests

​
Next Steps

Generate API Keys

Create keys for API access