OAuth & Developer Apps

Build integrations that work across multiple EsperWorks businesses. Developer accounts let you create OAuth apps that any business can authorise; no shared API keys needed.

API keys vs OAuth - If you are integrating your own single business (automating your own invoices), use a regular API key. OAuth is for multi-tenant apps where many different businesses connect to your platform.

1. Create a developer account

curl -X POST https://api.tryesperworks.com/api/v1/auth/register-developer \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "you@example.com",
    "password": "yourpassword",
    "password_confirmation": "yourpassword"
  }'

# Response:
# { "token": "...", "user": { "id": 1, "role": "developer" } }

2. Create an OAuth app

From your developer dashboard or via API using your developer token:

curl -X POST https://api.tryesperworks.com/api/v1/developer/apps \
  -H "Authorization: Bearer <developer_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "description": "Syncs invoices with my platform",
    "redirect_uri": "https://myapp.com/oauth/callback"
  }'

# Response:
# {
#   "app": { "client_id": "ew_app_xxxx", ... },
#   "client_secret": "ew_secret_xxxx"  ← shown only once
# }

Save the client_secret immediately; it is shown only once. You can rotate it later from the dashboard.

3. Redirect the user to authorise

Send the business owner to the EsperWorks authorisation page. They log in and approve the scopes your app requests. Always include a state parameter to prevent CSRF attacks.

# Redirect the business owner to this URL in their browser:
https://tryesperworks.com/oauth/authorize
  ?client_id=ew_app_xxxx
  &redirect_uri=https://myapp.com/oauth/callback
  &scope=invoices:read+clients:read
  &state=random_csrf_token

4. Exchange the code for an access token

After approval, EsperWorks redirects to your redirect_uri with a ?code= query param. Exchange it for an access token server-side:

curl -X POST https://api.tryesperworks.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "ew_app_xxxx",
    "client_secret": "ew_secret_xxxx",
    "code": "<code_from_callback>",
    "redirect_uri": "https://myapp.com/oauth/callback"
  }'

# Response:
# { "access_token": "...", "token_type": "Bearer", "business_id": 42 }

5. Make API calls on behalf of the business

Use the access token as a Bearer token. All requests are automatically scoped to the business that authorised your app.

curl https://api.tryesperworks.com/api/v1/invoices \
  -H "Authorization: Bearer <access_token>"

Revoking access

Business owners can revoke access at any time from their dashboard under Connected Apps. You can also revoke programmatically via POST /businesses/{business_id}/oauth/revoke.