API Keys

API keys allow programmatic access to PBS Knowledge without requiring interactive login. They're useful for scripts, integrations, data exports, and automated workflows.

Overview

• Secure: Keys are encrypted and never stored in plain text
• Scoped: Keys only have permissions you grant them
• Time-limited: Keys expire automatically (max 365 days)
• Tracked: Usage is logged with timestamps and IP addresses

Creating an API Key

1. Log in to PBS Knowledge
2. Go to Settings (click your name in the top right)
3. Select API Keys tab
4. Click Create New Key
5. Fill in the form:
   • Name: A descriptive name (e.g., "Research Data Export")
   • Permissions: Select what the key can access
   • Expiration: When the key should stop working
6. Click Create
7. Copy the key immediately - you won't be able to see it again!

Using Your API Key

Include the key in the X-API-Key header when making requests:

Example: curl

curl https://dartmouthpbs.org/api/courses \
  -H "X-API-Key: pbs_your_key_here"

Example: Python

import requests

API_KEY = "pbs_your_key_here"
BASE_URL = "https://dartmouthpbs.org/api"

# Get all courses
response = requests.get(
    f"{BASE_URL}/courses",
    headers={"X-API-Key": API_KEY}
)
courses = response.json()

# Get faculty members
response = requests.get(
    f"{BASE_URL}/people?type=Faculty",
    headers={"X-API-Key": API_KEY}
)
faculty = response.json()

Example: JavaScript/Node.js

const API_KEY = 'pbs_your_key_here';
const BASE_URL = 'https://dartmouthpbs.org/api';

// Get all courses
const response = await fetch(`${BASE_URL}/courses`, {
  headers: { 'X-API-Key': API_KEY },
});
const courses = await response.json();

Example: R

library(httr)

api_key <- "pbs_your_key_here"
base_url <- "https://dartmouthpbs.org/api"

# Get all courses
response <- GET(
  paste0(base_url, "/courses"),
  add_headers("X-API-Key" = api_key)
)
courses <- content(response, "parsed")

Available Endpoints

With an API key, you can access these endpoints (depending on permissions):

Endpoint	Description
GET /api/courses	List all courses
GET /api/people	List people (filter by type: Faculty, Staff, etc.)
GET /api/people/:id	Get a specific person's details
GET /api/labs	List all labs
GET /api/publications	List publications
GET /api/research-centers	List research centers
GET /api/resources	List resources
GET /api/degrees	List degree programs

Permissions

When creating a key, you can only grant permissions that you have. Common permissions include:

Permission	Description
read_courses	View course information
read_people	View people profiles
read_publications	View publications
read_labs	View lab information
read_resources	View resources

Faculty and staff may have additional permissions for writing/editing data.

Managing Your Keys

View Your Keys

Go to Settings → API Keys to see all your keys with:

• Name and creation date
• Key prefix (for identification)
• Status (active, expired, revoked)
• Last used timestamp
• Expiration date

Revoke a Key

If a key is compromised or no longer needed:

1. Go to Settings → API Keys
2. Find the key in the list
3. Click Revoke

Revoked keys immediately stop working and cannot be reactivated.

Delete a Key

To permanently remove a revoked key:

1. Revoke the key first (if active)
2. Click Delete

Best Practices

1. Use descriptive names - Name keys after their purpose (e.g., "Lab Website Integration")
2. Minimize permissions - Only grant what's actually needed
3. Set reasonable expirations - Don't use max expiration if not needed
4. Never share keys - Each person/system should have their own key
5. Don't commit to git - Store keys in environment variables
6. Rotate regularly - Create new keys and revoke old ones periodically
7. Monitor usage - Check "last used" to detect unauthorized access

Troubleshooting

"Invalid API key"

• Verify the key is copied correctly (no extra spaces)
• Check if the key has expired
• Confirm the key hasn't been revoked

"Permission denied"

• The key doesn't have the required permission for that endpoint
• Create a new key with the needed permission

"API key required"

• Make sure you're including the X-API-Key header
• Check the header name is exactly X-API-Key (case-sensitive)

Rate Limits

API keys are subject to rate limiting to prevent abuse:

• 100 requests per minute for read operations
• 20 requests per minute for write operations

If you hit rate limits, you'll receive a 429 Too Many Requests response.