Back to API documentation
# Company Redirect Guide This guide describes `GET /api/redirect/company/{company_id}`, an authenticated helper that deep-links a user into the Lightning Payroll Pays screen for a specific company. Base URL used in examples: ```text https://api.dev.intellitron.com.au ``` ## What this endpoint does When the request succeeds, Lightning Payroll: 1. validates that the caller is authenticated 2. loads the target company by Lightning Payroll `company_id` 3. checks that the caller has access to that company and has permission to view payroll data 4. updates the currently selected company for that customer account 5. applies the normal company lock checks 6. returns an HTTP `302` redirect to the front-end Pays route for that company The redirect target uses the frontend host that matches the current API host region. ## What this endpoint does not do This endpoint does **not**: - create a Lightning Payroll web session - perform OAuth login - accept `client_id` / `client_secret` - bypass company-level permissions - return a JSON success payload If you need API authentication or customer authorization, use the OAuth flow described in the OAuth authentication guide instead. ## When to use it Use this endpoint when: - the user is already authenticated with Lightning Payroll - you want to send them directly to the Pays screen for a known company - you want Lightning Payroll to update its selected-company context before opening the UI Typical use cases: - an internal operations tool linking a user straight into Pays - a browser-based admin flow where the user already has a valid Lightning Payroll session - Swagger or an HTTP client when you want to inspect the resulting redirect target ## When not to use it Do not use this endpoint as: - a general-purpose SSO entry point - a backend-only API integration expecting JSON data - a substitute for OAuth login - a background prefetch or health-check URL Because it updates the selected company, you should only call it when you genuinely want to move the user into that company context. ## Authentication requirements This endpoint uses normal authenticated Lightning Payroll API access. For programmatic calls, send a bearer token: ```bash ACCESS_TOKEN="<lightning-payroll-access-token>" ``` `GET` access requires: - a valid authenticated bearer token - `payroll.read` or `payroll.write` scope on that token - permission to access the target company Important: - calling this endpoint with an API token does not log the browser into the Lightning Payroll web app - a server-side HTTP client will only receive the redirect response; it will not create a usable browser session - for an actual browser deep-link, the user should already be authenticated in the Lightning Payroll web app context ## Request ### Endpoint ```text GET /api/redirect/company/{company_id} ``` ### Path parameters | Parameter | Type | Required | Notes | |---|---|---|---| | `company_id` | integer | Yes | Lightning Payroll company identifier | ### Example request ```bash curl -i -sS "https://api.dev.intellitron.com.au/api/redirect/company/123" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Successful response On success, the server returns HTTP `302 Found` with a `Location` header pointing at the Pays screen for that company. Example: ```http HTTP/1.1 302 Found Location: https://app.dev.intellitron.com.au/admin/pays/company/123 ``` The exact frontend hostname depends on the request origin region: - AU-origin requests redirect to the AU frontend - NZ-origin requests redirect to the NZ frontend ## Side effects Before issuing the redirect, the server changes the customer's selected-company state: - the selected company is updated to the target company - the normal company lock logic is applied That means this endpoint is stateful. Avoid calling it from: - speculative browser preloads - monitoring checks - background synchronization jobs ## Browser integration guidance For the intended user experience, use this endpoint as a top-level browser navigation in an already authenticated Lightning Payroll session. Recommended pattern: 1. ensure the user is already logged into Lightning Payroll 2. navigate the browser to `/api/redirect/company/{company_id}` 3. let the `302` send the user to `/admin/pays/company/{company_id}` If you call it with `fetch`, `XMLHttpRequest`, or a server-side HTTP client, you should expect redirect semantics only. That may be useful for inspection, but it is not the same as moving a signed-in user through the UI. ## Common errors | Status | Response detail | Meaning | |---|---|---| | `401` | `Could not validate credentials` | Request failed shared authentication before the route ran | | `403` | `Authorization token is missing or invalid.` | Bearer token was missing or malformed for company-access validation | | `403` | `User does not have read access to payroll data.` | Token scope did not include `payroll.read` or `payroll.write` | | `403` | `User does not have access to this company.` | Authenticated user is not allowed to access the target company | | `404` | `No company found with the given company_id` | The requested company does not exist for that customer context | ## Integration checklist 1. Treat this as a UI deep-link helper, not a data API. 2. Only call it for users who are already authenticated to Lightning Payroll. 3. Expect an HTTP `302`, not JSON. 4. Do not prefetch it, because it changes selected-company state. 5. Use the OAuth guides for authentication and token management; use this route only after authentication is already solved.