Authentication

API keys, OIDC integration, rate limits, and security best practices.

API Keys

Server-to-server authentication for API access

# Include API key in Authorization header
curl -X POST https://api.nobleid.org/v1/works \
  -H "Authorization: Bearer nbl_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"title": "My Paper", ...}'

# Or use query parameter (not recommended for production)
curl "https://api.nobleid.org/v1/works?api_key=nbl_live_1234567890abcdef..."

Key Management

• Keys are prefixed with nbl_live_ (production) or nbl_test_ (sandbox)
• Keys are shown only once during creation - store them securely
• Rotate keys regularly and before team member departures
• Use environment variables, never hardcode in source

Manage API Keys

API Key Scopes

Fine-grained permissions for different use cases

# API key scopes determine permissions:

works:read     # Read work metadata and versions
works:write    # Create and update works
works:delete   # Delete works (admin only)

receipts:read  # Access cryptographic receipts
receipts:verify # Verify receipt signatures

people:read    # Read author profiles
people:write   # Update author profiles

search:read    # Search works and people

admin:*        # Full administrative access

Scope Guidelines

• Request only the minimum scopes needed
• Use separate keys for different applications
• Read-only keys for analytics and monitoring
• Admin scopes require additional verification

Rate Limits

Request limits and best practices for high-volume usage

# Rate limits by endpoint:
GET  /v1/resolve/*        1000/hour per IP
GET  /v1/works/*          100/minute per API key
POST /v1/works            50/minute per API key
GET  /v1/search/*         200/minute per API key

# Headers returned:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400

# When rate limited (429 status):
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}

Best Practices

• Implement exponential backoff for retries
• Cache responses when possible
• Use batch endpoints for bulk operations
• Monitor rate limit headers
• Contact us for higher limits if needed

Error Handling

Common authentication errors and how to handle them

# Common authentication errors:

# 401 Unauthorized - Missing or invalid API key
{
  "error": "unauthorized",
  "message": "Invalid API key"
}

# 403 Forbidden - Insufficient permissions
{
  "error": "forbidden", 
  "message": "API key lacks required scope: works:write"
}

# 429 Too Many Requests - Rate limit exceeded
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}

Error Recovery

• 401: Check API key validity and format
• 403: Verify required scopes are granted
• 429: Implement retry with exponential backoff
• 5xx: Retry with jitter, contact support if persistent

OIDC for Author Login

OpenID Connect integration for author authentication

# OIDC configuration for author login:
Issuer: https://auth.nobleid.org
Authorization: https://auth.nobleid.org/oauth/authorize
Token: https://auth.nobleid.org/oauth/token
UserInfo: https://auth.nobleid.org/oauth/userinfo

# Supported scopes:
openid profile email
nobleid:author:read nobleid:author:write

# Example authorization URL:
https://auth.nobleid.org/oauth/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=openid+profile+nobleid:author:read&
  state=random_state_value

Use Cases

• Author profile management
• Work ownership claims
• Publisher dashboard access
• Institutional SSO integration

Setup Required

OIDC integration requires application registration and approval.

Request OIDC Setup

Security Best Practices

API Key Security

✓ Store keys in environment variables or secure vaults
✓ Use HTTPS for all API requests
✓ Rotate keys regularly (every 90 days recommended)
✓ Use different keys for different environments
✓ Monitor key usage and set up alerts
✗ Never commit keys to version control
✗ Never log API keys in application logs
✗ Never share keys via email or chat

Network Security

✓ Validate SSL certificates
✓ Use certificate pinning for mobile apps
✓ Implement request signing for sensitive operations
✓ Use IP allowlists for server-to-server communication