> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and API key overview for OMOPHub

> Understand OMOPHub authentication options including API keys and bearer tokens, scopes, header usage, and security best practices for API access.

## 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

<AccordionGroup>
  <Accordion title="Personal API Keys" icon="user">
    Individual developer keys

    * Tied to your user account
    * Inherit your account permissions
    * Usage counts toward personal quota
    * Can be revoked anytime
  </Accordion>

  <Accordion title="Team API Keys" icon="users">
    Shared keys for team collaboration (Coming Soon)

    * Associated with team/organization
    * Shared usage limits
    * Role-based access control
    * Audit logging per team member
  </Accordion>
</AccordionGroup>

## Authentication Flow

### API Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Auth Service
    
    Client->>API: Request with API key
    API->>Auth Service: Validate API key
    Auth Service->>API: Return permissions
    API->>Client: Process request
```

### API Key Security

1. **Environment Variables**: Store keys in environment variables
   ```bash theme={null}
   export OMOPHUB_API_KEY="oh_xxxxxxxxx"
   ```

2. **Key Rotation**: Regularly rotate keys (every 90 days recommended)

3. **Separate Environments**: Use different keys for dev/staging/production

4. **Monitor Usage**: Check API key usage regularly for anomalies

## Authentication Headers

### API Key Authentication

Include your API key in the Authorization header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer oh_xxxxxxxxx" \
    https://api.omophub.com/v1/vocabularies
  ```

  ```python Python theme={null}
  client = OMOPHubClient(api_key="oh_xxxxxxxxx")
  ```

  ```r R theme={null}
  client <- omophub_client(api_key = "oh_xxxxxxxxx")
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Not Working">
    * Check the key hasn't been revoked
    * Verify you're using the correct environment
    * Confirm proper Authorization header format
  </Accordion>

  <Accordion title="Rate Limit Exceeded">
    * Check X-RateLimit headers in responses
    * Implement exponential backoff
    * Consider upgrading your plan
    * Use caching to reduce requests
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Generate API Keys" icon="key" href="https://dashboard.omophub.com/api-keys">
    Create keys for API access
  </Card>
</CardGroup>