Authentication

Authentication

Learn how to authenticate with the OpenSauce API.

Overview

The OpenSauce API supports two authentication methods:

1. API Keys - For programmatic access from your applications
2. Session Cookies - For user authentication via GitHub OAuth

API Key Authentication

Use API keys for server-to-server communication or client-side applications where you control the environment.

How to Use

Include your API key in the Authorization header:

const response = await fetch('https://api.os.eura.dev/api/v1/recipes', {
  headers: {
    'Authorization': `Bearer YOUR_API_KEY`
  }
});

Creating API Keys

1. Go to the Dashboard
2. Navigate to API Keys
3. Click Create API Key
4. Give it a descriptive name
5. Copy the key (you won’t see it again!)

Best Practices

• Never commit API keys to version control
• Use environment variables in production:

  const apiKey = process.env.OPENSAUCE_API_KEY;

• Rotate keys regularly - Create new keys and revoke old ones
• Use different keys for different environments (development, staging, production)

Rate Limiting

API key requests are rate limited to 100 requests per minute per key.

Session Authentication

Session authentication is used for user-specific actions like:

• Submitting recipes
• Managing your account
• Accessing your personal data

How It Works

1. Sign in via GitHub OAuth

   • Visit dash.os.eura.dev/login
   • Click “Sign in with GitHub”
   • Authorize the application
   • You’ll receive a session cookie

2. Use the session cookie

   const response = await fetch('https://api.os.eura.dev/api/v1/recipes', {
     credentials: 'include' // This sends cookies
   });

Checking Your Session

// Get current user info
const response = await fetch('https://api.os.eura.dev/api/v1/auth/me', {
  credentials: 'include'
});

const user = await response.json();
// { id: 'usr_xxx', username: 'your-username', githubId: '12345' }

Signing Out

// Clear your session
const response = await fetch('https://api.os.eura.dev/api/v1/auth/logout', {
  method: 'POST',
  credentials: 'include'
});

GitHub OAuth Flow

For custom integrations, you can implement the OAuth flow:

Step 1: Redirect to GitHub

const githubUrl = `https://api.os.eura.dev/api/v1/auth/github?redirect_uri=${encodeURIComponent('YOUR_CALLBACK_URL')}`;
window.location.href = githubUrl;

Step 2: Handle Callback

After GitHub redirects back to your callback URL with a code parameter:

// The API handles the token exchange automatically
// You'll receive a session cookie in the response

Comparing Authentication Methods

Feature	API Key	Session Cookie
Best for	Application access	User actions
Required for	Public endpoints	Protected endpoints
Rate limited	Yes (100/min)	Yes (higher limit)
User context	No	Yes
Can submit recipes	No	Yes

Protected Endpoints

The following endpoints require session authentication:

• POST /api/v1/recipes - Submit a recipe
• GET /api/v1/auth/me - Get current user
• POST /api/v1/auth/logout - Sign out
• PATCH /api/v1/admin/recipes/:id - Admin actions

Troubleshooting

401 Unauthorized

This error means your authentication failed. Check:

1. API Key: Is the key correct?
2. Header: Are you using the Bearer prefix?
3. Cookie: Are you including credentials: 'include'?
4. Session: Has your session expired?

403 Forbidden

This means you’re authenticated but don’t have permission. Check:

1. Endpoint: Are you using the correct authentication method?
2. Admin: Does this endpoint require admin access?
3. Scope: Does your API key have the right permissions?

429 Too Many Requests

You’ve hit the rate limit. Wait and try again, or consider:

1. Caching: Cache responses locally
2. Batching: Combine multiple requests
3. Upgrade: Contact us for higher limits