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. Register your app in the OAuth Apps dashboard to get started.

OIDC Integration Guide Register OAuth App

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