Setup guide

This guide is structured as a compact API reference for the first steps of a Routix integration: obtaining credentials, requesting a token, and testing an endpoint.

User level: Advanced

API root endpoint

https://api.routix.com/v1

Most integrations start with these two URL patterns:

• OAuth token: https://api.routix.com/v1/oauth/token
• API proxy: https://api.routix.com/v1/{scopeId}/{resource}

What you need

• 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

Before making API calls, create an OAuth app in the 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.

Important: store the client_secret in a secrets manager.

Step 2: Find your scope UUIDs

Every API call requires the correct scope UUID for the target resource.

1. Go to Settings -> Organization to find your organization UUID, for example 123e4567-e89b-12d3-a456-426614174000.
2. Go to Settings -> Branches to find your branch UUID, for example 550e8400-e29b-41d4-a716-446655440000.
3. Use the organization UUID for branches, organizations, users, and master_data.
4. Use the branch UUID for branch-scoped resources such as accounts, projects, and shipments.

Call 1: Request an access token

Use this call to obtain a machine-to-machine token for your integration.

Use the client credentials flow for your integration:

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

Request body:

Example response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "routix:accounts:read routix:accounts:write",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Key response fields:

Common errors:

Call 2: Test your token with an API request

Use your new token immediately on a read endpoint to confirm authentication, scope, and branch access are correct.

With your token and branch UUID, make a request:

curl -X GET "https://api.routix.com/v1/550e8400-e29b-41d4-a716-446655440000/accounts?limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Query parameters:

Example response:

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

Validation check:

• 200 OK: token, scope, and branch UUID are correct.
• 401 invalid_token: request a new token.
• 403 insufficient_scope: add routix:accounts:read to the app.
• 404 branch_not_found: verify the branch UUID.

Manage app status

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

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

Troubleshooting

Available scopes reference

Integration checklist

• Register an OAuth app in Routix.
• Store client_id and client_secret securely.
• Implement token acquisition with the client credentials flow.
• Handle token expiry by requesting a new token.
• Use the correct branch UUID in API URLs.
• Request only the scopes your app needs.
• Handle error responses such as 401, 403, 404, and 429.
• Test with v1 for stable field contracts.

Related pages

• API integration
• API calls & examples