Authentication

The SoapBox API supports API key authentication for server-to-server requests and OAuth 2.0 for user-authorized access.

API Key Authentication

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

curl https://api.soapboxsuperapp.com/api/v1/churches \
  -H "Authorization: Bearer sk_live_xxxxx"

Or use the X-API-Key header:

curl https://api.soapboxsuperapp.com/api/v1/churches \
  -H "X-API-Key: sk_live_xxxxx"

Creating API Keys

1. Go to your Dashboard
2. Select an app
3. Navigate to API Keys
4. Click "Create New Key"

OAuth 2.0

OAuth 2.0 allows users to authorize your app to access their data without sharing their password. We support the Authorization Code flow with PKCE.

Authorization Flow

Step 1: Redirect to Authorization

Redirect users to our authorization endpoint:

https://api.soapboxsuperapp.com/api/v1/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:churches read:events
  &state=random_state_string

Step 2: Handle the Callback

After authorization, we redirect back with a code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_string

Step 3: Exchange Code for Token

curl -X POST https://api.soapboxsuperapp.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "scope": "read:churches read:events"
}

PKCE (for Public Clients)

For SPAs and mobile apps, use PKCE to secure the authorization flow:

import { OAuth } from '@soapbox/sdk';

const oauth = new OAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback'
});

// Generate PKCE challenge
const pkce = await oauth.generatePKCE();
sessionStorage.setItem('code_verifier', pkce.codeVerifier);

// Build authorization URL
const authUrl = oauth.getAuthorizationUrl({
  scope: 'read:churches read:events',
  codeChallenge: pkce.codeChallenge
});

// Redirect user
window.location.href = authUrl;

Refreshing Tokens

curl -X POST https://api.soapboxsuperapp.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Scopes

Scopes control what data your app can access:

Error Responses