API Authentication

The 200Notes API uses Bearer token authentication to secure access to your data. This guide will walk you through generating API tokens and making authenticated requests.

Authentication Overview

Authentication Method

200Notes uses Bearer token authentication for API access:

• Type: Bearer Token
• Header: Authorization: Bearer YOUR_TOKEN
• Scope: Tokens inherit your account permissions
• Expiration: Tokens don't expire but can be revoked

Generating API Tokens

Personal Access Tokens

Create personal access tokens for your own applications:

1. Log into your 200Notes account
2. Go to Settings → API Keys
3. Click "Generate New Token"
4. Give your token a descriptive name
5. Select the appropriate scopes
6. Click "Create Token"
7. Copy the token immediately (it won't be shown again)

Token Scopes

Control what your token can access with scopes:

Token Best Practices

Making Authenticated Requests

Authorization Header

Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Complete Request Example

Here's a complete authenticated request using the actual API format:

curl -X GET \
  https://200notes.com/api/v1/projects \
  -H "Authorization: Bearer sk-abc123:xyz789" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Raw HTTP Examples

Examples using different HTTP clients:

cURL

curl -X GET \
  https://200notes.com/api/v1/projects \
  -H "Authorization: Bearer sk-abc123:xyz789" \
  -H "Content-Type: application/json"

JavaScript (fetch)

fetch('https://200notes.com/api/v1/projects', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk-abc123:xyz789',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer sk-abc123:xyz789',
    'Content-Type': 'application/json'
}

response = requests.get('https://200notes.com/api/v1/projects', headers=headers)
data = response.json()

OAuth 2.0 (Coming Soon)

OAuth Flow

For third-party applications, we'll be adding OAuth 2.0 support:

• Authorization Code Flow: For server-side applications
• Implicit Flow: For client-side applications
• Client Credentials Flow: For service-to-service
• Refresh Tokens: For long-lived access

OAuth Scopes

OAuth will support fine-grained permissions:

• openid: Basic profile information
• profile: Full profile access
• email: Email address access
• projects: Project access
• notes: Note access
• tasks: Task access

Error Handling

Authentication Errors

Common authentication error responses:

401 Unauthorized - Missing Token

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "message": "Authentication required",
    "code": "MISSING_TOKEN"
  }
}

401 Unauthorized - Invalid Token

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "message": "Invalid authentication token",
    "code": "INVALID_TOKEN"
  }
}

403 Forbidden - Insufficient Permissions

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "message": "Insufficient permissions for this action",
    "code": "INSUFFICIENT_PERMISSIONS",
    "details": {
      "required_scope": "write",
      "provided_scope": "read"
    }
  }
}

Handling Authentication Errors

Best practices for error handling:

• Check Status Codes: Always check HTTP status codes
• Parse Error Messages: Extract meaningful error information
• Retry Logic: Implement appropriate retry strategies
• User Feedback: Provide clear error messages to users
• Logging: Log authentication failures for debugging

Token Management

Viewing Active Tokens

Manage your tokens from the settings page:

• Token List: View all active tokens
• Last Used: See when each token was last used
• Permissions: View token scopes
• Usage Stats: Monitor token usage

Revoking Tokens

Revoke tokens when they're no longer needed:

1. Go to Settings → API Keys
2. Find the token you want to revoke
3. Click "Revoke"
4. Confirm the revocation

Token Rotation

Regularly rotate your tokens for security:

1. Generate a new token with the same scopes
2. Update your applications to use the new token
3. Test that the new token works correctly
4. Revoke the old token
5. Monitor for any errors

Security Considerations

Token Storage

Store tokens securely in your applications:

• Environment Variables: Use env vars for server-side apps
• Secure Storage: Use secure storage APIs for mobile apps
• Encryption: Encrypt tokens at rest
• Access Control: Limit who can access tokens

Network Security

Protect tokens in transit:

• HTTPS Only: Always use HTTPS for API requests
• Certificate Pinning: Pin certificates in mobile apps
• Request Signing: Consider request signing for sensitive operations
• IP Restrictions: Restrict tokens to specific IP addresses

Monitoring and Auditing

Monitor token usage for security:

• Usage Logs: Monitor token usage patterns
• Anomaly Detection: Detect unusual usage patterns
• Regular Audits: Review active tokens regularly
• Incident Response: Have a plan for token compromise

Testing Authentication

Test Your Token

Verify your token works correctly:

# Test with curl
curl -X GET \
  https://200notes.com/api/v1/user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.200notes.v1+json"

Expected Response

A successful authentication test returns:

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Your Name",
    "email": "you@example.com",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Common Issues

Troubleshoot authentication problems:

• Token Not Working: Check for typos in the token
• Permission Denied: Verify token has required scopes
• Invalid Format: Ensure proper Authorization header format
• Expired Token: Tokens don't expire but can be revoked

Migration Guide

From API Keys to Tokens

If you're upgrading from our legacy API key system:

1. Generate new Bearer tokens with appropriate scopes
2. Update your applications to use Bearer authentication
3. Test thoroughly in a staging environment
4. Deploy to production
5. Revoke old API keys

Code Updates

Update your authentication code:

Before (API Key)

curl -X GET \
  https://200notes.com/api/v1/projects \
  -H "X-API-Key: YOUR_API_KEY"

After (Bearer Token)

curl -X GET \
  https://200notes.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Rate Limiting

Authentication Rate Limits

Rate limits apply to authentication attempts:

• Failed Attempts: 5 failed attempts per minute
• Token Generation: 10 tokens per hour
• Token Revocation: 100 revocations per hour

Rate Limit Headers

Authentication-specific rate limit headers:

X-Auth-RateLimit-Limit: 5
X-Auth-RateLimit-Remaining: 4
X-Auth-RateLimit-Reset: 1642248000