Authentication

All API requests require authentication. We support API keys for server-to-server communication and OAuth 2.0 for user-authorized access.

API Keys

API keys are the simplest way to authenticate. Include your API key in the Authorization header:

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

Using the SDK

If you're using our SDK, authentication is handled automatically. Just pass your API key when initializing the client.

API Key Types

We offer different types of API keys for different use cases:

Type	Prefix	Use Case
Live	`sk_live_`	Production environment
Test	`sk_test_`	Development and testing
Restricted	`rk_`	Limited scope access

OAuth 2.0

For applications that need to access user data, we support OAuth 2.0 with the authorization code flow:

1. Redirect to authorization

const authUrl = new URL('https://api.example.com/oauth/authorize');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'read:users write:users');

// Redirect the user
window.location.href = authUrl.toString();

2. Exchange code for token

const response = await fetch('https://api.example.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code: 'AUTHORIZATION_CODE',
    redirect_uri: 'https://yourapp.com/callback',
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

3. Use the access token

const response = await fetch('https://api.example.com/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
  },
});

Permission Scopes

Scopes define what actions your application can perform. Request only the scopes you need:

Scope	Description
`read:users`	Read user information
`write:users`	Create and update users
`read:products`	Read product data
`write:products`	Create and update products
`read:orders`	Read order information
`write:orders`	Create and manage orders

Security Best Practices

Keep your credentials secure

Never expose your API keys or client secrets in client-side code or public repositories.

Use environment variables - Store keys in environment variables, not in code
Rotate keys regularly - Create new keys and revoke old ones periodically
Use restricted keys - Create keys with only the permissions you need
Monitor usage - Check your dashboard for unusual activity
Use HTTPS - All API requests must use HTTPS