API Key Guide

Overview

This guide explains how to obtain and manage API keys for accessing WeTrials public data APIs. API keys provide simple authentication for accessing public clinical trial data and integrating widgets like Labrador.

Table of Contents

1. What is an API Key?
2. How to Obtain an API Key
3. API Key Security
4. Using Your API Key
5. Rate Limits
6. Troubleshooting

What is an API Key?

An API key is a unique identifier used to authenticate requests to WeTrials public data APIs. It helps us:

• Identify your application
• Track API usage
• Apply appropriate rate limits
• Provide access to public clinical trial data

API Key vs OAuth

Feature	API Key	OAuth 2.0
Use Case	Public data access	Private/user-specific data
Complexity	Simple integration	More complex flow
Data Access	Public clinical trials, studies	Patient data, personal information
Authentication	Single key	Token-based with refresh
Typical Usage	Widgets, public search	Server-to-server, user apps

How to Obtain an API Key

Step 1: Contact WeTrials Team

To request an API key, please contact our development team through one of the following methods:

• Email: api-support@wetrials.com
• Slack: #api-support channel (for internal teams)
• Support Portal: https://support.wetrials.com

Step 2: Provide Required Information

When requesting an API key, please provide:

1. Organization Name: Your company or organization name
2. Contact Information:
   • Primary contact name
   • Email address
   • Phone number (optional)
3. Use Case: Brief description of how you'll use the API
4. Expected Traffic: Estimated number of API calls per month
5. Environment: Development, staging, or production

Step 3: API Key Delivery

Once approved, you will receive:

• API Key: A unique alphanumeric string
• Organization ID: Your organization identifier
• Documentation: Links to relevant API documentation
• Support Contact: Direct support channel for issues

Sample Request Email

Subject: API Key Request for [Your Organization]

Hello WeTrials API Team,

I would like to request an API key for our organization.

Organization: [Your Organization Name]
Contact: [Your Name]
Email: [Your Email]
Use Case: [Brief description of your integration]
Expected Traffic: [Estimated monthly API calls]
Environment: [Development/Production]

Thank you for your assistance.

Best regards,
[Your Name]

API Key Security

Best Practices

1. Never Commit to Version Control

   // ❌ Bad: Hardcoded API key
   const apiKey = '1I47uhByUg-AEaVBMJHhy8LACpVn4D1zjzH1SRxmveE';
   
   // ✅ Good: Use environment variables
   const apiKey = process.env.WETRIALS_API_KEY;

2. Use Environment Variables

   # .env file (add to .gitignore)
   WETRIALS_API_KEY=your-api-key-here
   WETRIALS_ORG_ID=your-org-id

3. Restrict Access

   • Store API keys securely
   • Limit access to authorized personnel only
   • Use different keys for different environments

4. Monitor Usage

   • Regularly check API usage logs
   • Set up alerts for unusual activity
   • Review access patterns periodically

Key Rotation

We recommend rotating API keys periodically:

• Development Keys: Every 6 months
• Production Keys: Every 12 months
• Compromised Keys: Immediately

To rotate your key, contact our support team with your current key information.

Using Your API Key

With Labrador Widget

Labrador({
  shadowRoot: document.getElementById('study-finder'),
  shadowModalRoot: document.getElementById('modal-root'),
  env: 'production', // or 'development'
  orgId: 'your-org-id',
  apiKey: 'your-api-key-here', // Your API key
});

Direct API Calls

// Fetch studies with API key
const response = await fetch(`https://api.wetrials.com/v2/labrador/study?apiKey=${apiKey}`);
const data = await response.json();

Header Authentication (Alternative)

// Using Authorization header
const response = await fetch('https://api.wetrials.com/v2/labrador/study', {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});

Rate Limits

API keys have the following default rate limits:

Tier	Requests per Minute	Requests per Day	Monthly Limit
Development	60	1,000	30,000
Standard	300	10,000	300,000
Enterprise	1,000	100,000	3,000,000

Rate Limit Headers

API responses include rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1640995200

Handling Rate Limits

async function makeAPICall(url, apiKey) {
  const response = await fetch(`${url}?apiKey=${apiKey}`);

  if (response.status === 429) {
    // Rate limited - wait and retry
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitTime = resetTime - Date.now() / 1000;

    console.log(`Rate limited. Waiting ${waitTime} seconds...`);
    await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));

    // Retry the request
    return makeAPICall(url, apiKey);
  }

  return response.json();
}

Troubleshooting

Common Issues

Invalid API Key Error

{
  "error": "Invalid API key",
  "code": "AUTH_001"
}

Solution: Verify your API key is correct and active. Contact support if the issue persists.

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "code": "RATE_001",
  "retry_after": 60
}

Solution: Implement exponential backoff or wait for the specified time before retrying.

Expired API Key

{
  "error": "API key expired",
  "code": "AUTH_002"
}

Solution: Contact support to renew your API key.

Organization Mismatch

{
  "error": "Organization ID does not match API key",
  "code": "AUTH_003"
}

Solution: Ensure you're using the correct organization ID with your API key.

Getting Help

If you encounter issues with your API key:

1. Check Documentation: Review this guide and API documentation
2. Verify Configuration: Ensure API key and organization ID are correct
3. Check Status Page: status.wetrials.com for service status
4. Contact Support:
   • Email: api-support@wetrials.com
   • Include your organization ID and error messages (never send API keys via email)

FAQ

Can I use the same API key for multiple environments?

We recommend using separate API keys for each environment (development, staging, production) for better security and usage tracking.

How long does it take to receive an API key?

Typically within 1-2 business days. For urgent requests, please indicate this in your request.

Can I have multiple API keys for the same organization?

Yes, you can request multiple API keys for different applications or environments.

What happens if my API key is compromised?

Contact support immediately at api-support@wetrials.com. We will deactivate the compromised key and issue a new one.

Is there a cost for API access?

Please contact our sales team for pricing information based on your usage requirements.

---

Last Updated: January 2024 Maintained By: WeTrials API Team