Setup guide

This guide walks you through creating your first API integration with Routix, from registering an OAuth app to making your first API call.

User level: Advanced

Prerequisites

• A Routix account with admin or owner access.
• At least one branch configured in your organization.
• A server or application that will consume the API.

Step 1: Register an OAuth app

Option A: Routix dashboard

1. Log in to Routix at app.routix.com.
2. Go to Settings -> OAuth Apps.
3. Click Create App.
4. Fill in the form.

5. Click Save.
6. Copy the client secret immediately. It is shown only once.

Option B: API

curl -X POST https://api.routix.com/functions/v1/register-oauth-app \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -d '{
    "name": "My ERP Sync",
    "description": "Syncs accounts from Routix to our ERP",
    "redirect_uris": ["https://myerp.com/callback"],
    "allowed_scopes": ["routix:accounts:read", "routix:accounts:write"],
    "allowed_branch_ids": []
  }'

Response:

{
  "success": true,
  "app": {
    "id": "a1b2c3d4-...",
    "name": "My ERP Sync",
    "client_id": "e5f6g7h8-...",
    "client_secret": "routix_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "redirect_uris": ["https://myerp.com/callback"],
    "allowed_scopes": ["routix:accounts:read", "routix:accounts:write"],
    "allowed_branch_ids": [],
    "status": "active",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "warning": "Store the client_secret securely. It will not be shown again."
}

Important: the client_secret has the format routix_<40 hex characters>. Store it in a secrets manager. If lost, rotate the secret.

Step 2: Find your branch ID

Every API call requires a public branch ID of 8 characters.

1. Go to Settings -> Branches in Routix.
2. Find the Public ID for the branch, for example RS2RDH3B.
3. Use this short ID in the API URL instead of the internal UUID.

Step 3: Get an access token

Backend integrations: Client credentials

curl -X POST https://api.routix.com/functions/v1/oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "routix_a1b2c3d4..."
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "routix:accounts:read routix:accounts:write",
  "organization_id": "org-uuid",
  "branch_ids": ["branch-uuid"]
}

User-facing apps: Authorization Code + PKCE

See the API integration page for the full OAuth flow.

Step 4: Make your first API call

With your token and branch ID, make a request:

curl -X GET "https://api.routix.com/functions/v1/api/v1/RS2RDH3B/accounts?limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Expected response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "company_name": "Acme Transport B.V.",
      "email": "info@acmetransport.nl",
      "phone": "+31 20 123 4567",
      "account_type": "customer",
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 1
  },
  "version": "v1"
}

Your API integration is now working.

Step 5: Rotate secrets

If your client secret is compromised, or as part of regular security hygiene, rotate it.

Via the dashboard

1. Go to Settings -> OAuth Apps -> Your App.
2. Click Rotate Secret.
3. Copy the new secret immediately.
4. Update your application configuration.

The old secret is invalidated immediately.

Via the API

curl -X POST https://api.routix.com/functions/v1/rotate-oauth-secret \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -d '{
    "oauth_app_id": "YOUR_APP_UUID"
  }'

Response:

{
  "success": true,
  "client_secret": "routix_new_secret_here...",
  "client_secret_last4": "s9t0",
  "warning": "Store the client_secret securely. It will not be shown again."
}

Existing tokens remain valid until they expire, with a maximum of 1 hour.

Step 6: Revoke or reactivate an app

Revoke

To block an app from requesting new tokens:

• In the dashboard: OAuth Apps -> Your App -> Revoke
• Via API: update the status to revoked on the oauth_apps resource

Revoking an app prevents new token requests, while existing tokens remain valid until they expire.

Reactivate

To re-enable a revoked app:

• In the dashboard: OAuth Apps -> Your App -> Activate
• Via API: update the status to active

Troubleshooting

Available scopes reference

Checklist

• Register an OAuth app in Routix.
• Store client_id and client_secret securely.
• Implement token acquisition with the appropriate OAuth flow.
• Handle token expiry and renewal.
• Use the correct 8-character branch public ID in API URLs.
• Request only the scopes your app needs.
• Handle error responses such as 401, 403, 404, and 429.
• Plan a secret rotation schedule.
• Test with v1 for stable field contracts.

Related pages

• API integration
• API calls & examples