Authentication - Dutchie Point of Sale API

🔐 Authentication

The Dutchie Point of Sale API uses API Key Authentication with HTTP Basic Auth to secure all API requests. This ensures that only authorized applications can access your business data.

📋 API Key Request Process

1. Contact Support

API keys are provided by Dutchie Support through our official support portal. Each key is vendor-specific and scoped to appropriate permissions.

Contact Dutchie Support with details about your integration needs and they will guide you through the API key request process.

2. Key Provisioning

Once approved, you'll receive separate API keys for each vendor relationship. Keys are permission-scoped based on your specific integration needs.

⚠️ Important: API keys are vendor-specific. A key issued for one vendor integration will not work for another vendor's data access.

🔐 Permission Scopes

API keys are granted specific permission scopes that control which endpoints and data you can access. Understanding these scopes is crucial for planning your integration. See the Permissions Guide for detailed information about all available scopes and their endpoints.

🎯 Requesting Appropriate Permissions

When requesting API keys, be specific about:

Your use case - What business problem are you solving?
Required data - What information do you need to access?
Operations needed - Do you need read-only or read-write access?
Specific endpoints - Which API endpoints will you be calling?

⚠️ Permission Errors: If you receive 403 Forbidden responses, your API key may not have the required permissions. Contact Dutchie Support to request additional scopes.

🔑 Using Your API Key

Basic Authentication

Use your API key as the username in HTTP Basic Authentication, leaving the password empty.

Authentication Header Format:

Authorization: Basic {base64_encoded_api_key}

Manual Encoding Example:

# If your API key is: abc123xyz
# Encode "abc123xyz:" (note the colon)
# Result: YWJjMTIzeHl6Og==

Authorization: Basic YWJjMTIzeHl6Og==

💡 Pro Tip: Most HTTP clients handle Basic Auth encoding automatically when you provide the API key as username with empty password.

🛡️ Security Best Practices

Key Storage

Environment Variables - Store keys in environment variables, not in code
Secure Configuration - Use secure configuration management systems
Never Commit Keys - Add API keys to your .gitignore file
Access Control - Limit key access to necessary personnel only

🔍 Testing Authentication

Quick Test - Verify API Key

Use the /whoami endpoint to verify your API key is working and see which location it accesses:

curl -X GET "https://api.pos.dutchie.com/whoami" \
  -H "Authorization: Basic {your_encoded_key}" \
  -H "Accept: application/json"

Expected Response

200 OK - Authentication successful, returns location information
401 Unauthorized - Invalid or missing API key
403 Forbidden - Valid key but insufficient permissions