Setup guide

Deze gids helpt je bij het opzetten van je eerste API-integratie met Routix, van het registreren van een OAuth-app tot je eerste API-call.

Gebruikersniveau: Gevorderd

Vereisten

• Een Routix-account met admin- of ownerrechten.
• Minimaal een branch binnen je organisatie.
• Een server of applicatie die de API gaat gebruiken.

Stap 1: Registreer een OAuth-app

Optie A: Routix dashboard

1. Log in op Routix via app.routix.com.
2. Ga naar Settings -> OAuth Apps.
3. Klik op Create App.
4. Vul het formulier in.

5. Klik op Save.
6. Kopieer de client secret direct. Deze wordt maar een keer getoond.

Optie B: Via de 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."
}

Belangrijk: de client_secret heeft het formaat routix_<40 hex characters>. Bewaar die in een secrets manager. Als je hem kwijt bent, roteer de secret.

Stap 2: Zoek je branch ID op

Voor elke API-call heb je een publieke branch ID van 8 tekens nodig.

1. Ga in Routix naar Settings -> Branches.
2. Zoek de Public ID van de branch op, bijvoorbeeld RS2RDH3B.
3. Gebruik deze korte ID in de API-URL in plaats van de interne UUID.

Stap 3: Vraag een access token aan

Backendintegraties: 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"]
}

Gebruikersgerichte apps: Authorization Code + PKCE

Zie de pagina API integratie voor de volledige OAuth-flow.

Stap 4: Doe je eerste API-call

Met je token en branch ID kun je een request doen:

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

Verwachte 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"
}

Je API-integratie werkt nu.

Stap 5: Roteer secrets

Als je client secret is gecompromitteerd, of als onderdeel van regulier securitybeheer, roteer je de secret.

Via het dashboard

1. Ga naar Settings -> OAuth Apps -> Your App.
2. Klik op Rotate Secret.
3. Kopieer de nieuwe secret direct.
4. Werk de configuratie van je applicatie bij.

De oude secret wordt meteen ongeldig gemaakt.

Via de 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."
}

Bestaande tokens blijven geldig tot ze verlopen, met een maximum van 1 uur.

Stap 6: Revoke of reactivate een app

Revoke

Om een app direct te blokkeren voor nieuwe tokenaanvragen:

• In het dashboard: OAuth Apps -> Your App -> Revoke
• Via API: update de status naar revoked op de oauth_apps resource

Een revoke voorkomt nieuwe tokenrequests, terwijl bestaande tokens geldig blijven tot expiry.

Reactivate

Om een gerevokeerde app weer te activeren:

• In het dashboard: OAuth Apps -> Your App -> Activate
• Via API: update de status naar active

Troubleshooting

Beschikbare scopes

Checklist

• Registreer een OAuth-app in Routix.
• Bewaar client_id en client_secret veilig.
• Implementeer token acquisition met de juiste OAuth-flow.
• Handel token expiry en vernieuwing correct af.
• Gebruik de juiste 8-karakter publieke branch ID in API-URL’s.
• Vraag alleen de scopes aan die je applicatie nodig heeft.
• Handel foutresponses zoals 401, 403, 404 en 429 af.
• Plan een schema voor secret rotation.
• Test met v1 voor stabiele veldcontracten.

Gerelateerde pagina’s

• API integratie
• API calls en voorbeelden