Authentication

The Crumb API supports two authentication methods: API keys for server-to-server integrations, and OAuth 2.0 for applications that act on behalf of Crumb merchants.

API Keys

API keys are the simplest way to authenticate. They're ideal for server-side integrations where your code can securely store the key.

Getting Your Keys

API keys are available in your Crumb dashboard under Settings → Developers → API Keys. You'll receive two keys:

• Test key (sk_test_...): For development and testing
• Live key (sk_live_...): For production use

Using API Keys

Include your API key in the Authorization header using the Bearer scheme:

curl https://api.crumbpos.com/v1/orders \
  -H "Authorization: Bearer sk_test_abc123..."

Key Permissions

By default, API keys have full access to your account. You can create restricted keys with specific permissions in your dashboard:

• Read-only: Can only fetch data, not create or modify
• Orders only: Access to orders endpoints only
• Menu only: Access to menu endpoints only
• Custom: Define your own permission set

OAuth 2.0

Use OAuth 2.0 when building applications that need to access Crumb accounts on behalf of merchants. This is required for apps listed in the Crumb App Marketplace.

OAuth Flow Overview

1. Register your application in the Crumb developer dashboard
2. Redirect merchants to Crumb's authorization page
3. Merchant approves your application
4. Crumb redirects back with an authorization code
5. Exchange the code for an access token
6. Use the access token for API requests

Step 1: Authorization Request

Redirect the merchant to:

https://dashboard.crumbpos.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=read_orders+write_menu&
  state=random_string_for_security

Step 2: Token Exchange

After the merchant approves, exchange the authorization code for tokens:

curl https://api.crumbpos.com/oauth/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Token Response

{
  "access_token": "at_live_abc123...",
  "refresh_token": "rt_live_xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read_orders write_menu"
}

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl https://api.crumbpos.com/oauth/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "rt_live_xyz789..."
  }'

OAuth Scopes

Request only the scopes your application needs:

Best Practices

• Store API keys and tokens securely using environment variables or a secrets manager
• Rotate API keys periodically and after any suspected compromise
• Use restricted keys with minimal permissions when possible
• Implement token refresh logic before tokens expire
• Handle authentication errors gracefully in your application