API Authentication

The Motorical Public API uses short-lived Bearer tokens with granular permission scopes. Tokens are bound to a specific Motor Block and expire after 5 minutes by default.

Getting a Token

Via the Dashboard

1. Go to Settings → API Access in your Motorical dashboard
2. Select a Motor Block (choose the one sending your emails)
3. Check the permissions you need
4. Click "Generate Token" (valid for 5 minutes)

Programmatically

curl -X POST https://api.motorical.com/api/public/token \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "motorBlockId": "YOUR_MOTOR_BLOCK_ID",
    "scopes": ["logs.read", "analytics.read", "usage.read"],
    "ttlSeconds": 300
  }'

Using the Token

Include the token in the Authorization header of every request:

Authorization: Bearer <TOKEN>

Permission Scopes

Scope	Access
logs.read	Search and read email delivery logs
analytics.read	Access metrics, providers, error codes, daily summaries
usage.read	View rate limits and usage counters
config.read	Read motor block configuration and domain health
logs.pii	Access unmasked recipient email addresses in logs
webhooks.manage	Create, update, and delete webhook endpoints

tip

For most integrations, start with logs.read, analytics.read, and usage.read. Add config.read if you need domain health or configuration endpoints.

Token Format

Tokens are signed RS256 JWTs containing:

• Motor Block ID binding
• Granted scopes
• Expiration timestamp
• Issuer verification

Common Errors

Status	Meaning	Fix
401 Unauthorized	Token missing, invalid, or expired	Generate a new token
403 Forbidden	Token lacks the required scope	Regenerate with the needed scope
403 Forbidden	Motor Block ID mismatch	Token is bound to a different Motor Block