Authentication

Learn how to authenticate with our API securely and effectively.

Authentication Methods

We support multiple authentication methods to fit different use cases:

API Keys

API keys are the simplest way to authenticate for server-to-server communication.

Creating an API Key

1. Log in to your account dashboard
2. Navigate to "API Keys" section
3. Click "Create New Key"
4. Copy and securely store your key

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_live_1234567890abcdef" \
     https://api.example.com/v1/users

OAuth 2.0

OAuth 2.0 is recommended for applications that need to access user data.

OAuth Flow

1. Authorization Request: Redirect users to our authorization endpoint
2. User Consent: Users grant permission to your application
3. Authorization Code: Receive an authorization code
4. Token Exchange: Exchange the code for an access token
5. API Access: Use the access token to make API requests

Authorization URL

https://auth.example.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=your_redirect_uri&
  response_type=code&
  scope=read write

Token Exchange

curl -X POST https://auth.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=your_redirect_uri" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

JWT Tokens

For stateless authentication, we support JSON Web Tokens (JWT).

JWT Structure

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user_123",
    "iat": 1640995200,
    "exp": 1641081600,
    "scope": "read write"
  }
}

Security Best Practices

API Key Security

• Never expose API keys in client-side code
• Use environment variables to store keys
• Rotate keys regularly for enhanced security
• Use different keys for different environments

OAuth Security

• Use HTTPS for all OAuth flows
• Validate state parameters to prevent CSRF attacks
• Store tokens securely on the server side
• Implement token refresh for long-lived applications

General Security

• Use HTTPS for all API requests
• Validate all inputs before making requests
• Implement rate limiting on your end
• Monitor for suspicious activity

Error Handling

Authentication Errors

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}

Common Error Codes

• invalid_api_key: API key is missing or invalid
• expired_token: Access token has expired
• insufficient_scope: Token doesn't have required permissions
• rate_limit_exceeded: Too many requests made

Testing Authentication

Test API Keys

Use our test API keys for development:

# Test key (sandbox environment)
Authorization: Bearer sk_test_1234567890abcdef

# Live key (production environment)
Authorization: Bearer sk_live_1234567890abcdef