00What this endpoint does
When the request succeeds, Lightning Payroll:
Validates that the caller is authenticated.
Loads the target company by Lightning Payroll company_id.
Checks that the caller has access to that company and permission to view payroll data.
Updates the currently selected company for that customer account.
Applies the normal company lock checks.
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.
01What it 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 Authentication Guide instead.
02When to use it, and when not
| Use it when… | Don't use it as… |
|---|---|
| The user is already authenticated with Lightning Payroll. | A general-purpose SSO entry point. |
| You want to send them directly to the Pays screen for a known company. | A backend-only API integration expecting JSON data. |
| You want Lightning Payroll to update its selected-company context before opening the UI. | A substitute for OAuth login. |
| Typical cases: an internal operations tool, a browser-based admin flow, or Swagger / an HTTP client inspecting the redirect target. | A background prefetch or health-check URL. |
Because it updates the selected company, only call it when you genuinely want to move the user into that company's context.
03Authentication requirements
This endpoint uses normal authenticated Lightning Payroll API access. GET access requires:
- a valid authenticated bearer token
- payroll.read or payroll.write scope on that token
- permission to access the target company
Calling this endpoint with an API token does not log the browser into the Lightning Payroll web app. A server-side HTTP client only receives the redirect response; it does not create a usable browser session. For an actual browser deep-link, the user must already be authenticated in the web app itself.
04Request
| Parameter | Type | Required | Notes |
|---|---|---|---|
company_id | integer | Yes | Lightning Payroll company identifier |
BASE_URL="https://<your-au-sandbox-api-host>" # AU sandbox # BASE_URL="https://<your-nz-sandbox-api-host>" # NZ sandbox curl -i -sS "$BASE_URL/api/redirect/company/123" \ -H "Authorization: Bearer $ACCESS_TOKEN"
05Successful response
On success, the server returns HTTP 302 Found with a Location header pointing at the Pays screen for that company.
HTTP/1.1 302 Found
Location: https://<your-au-sandbox-app-host>/admin/pays/company/123
For the NZ sandbox, the matching frontend host is:
Location: https://<your-nz-sandbox-app-host>/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.
06Side effects
Before issuing the redirect, the server changes the customer's selected-company state: the selected company is updated to the target company, and 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
07Browser integration guidance
This endpoint cannot be used as a plain browser link. Authentication comes from the Authorization header and nothing else. A top-level browser navigation cannot set a header, and the Lightning Payroll web app holds its session token in localStorage rather than a cookie, so there is nothing on the request for the server to read. Following this URL as a link returns 401 whether or not the user has a live session.
Earlier revisions of this guide recommended exactly that pattern. They were wrong, and the correction is the reason this section exists.
Use it only from a caller that can set the header: your own server-side code, an HTTP client, or an in-app fetch that attaches the token and then navigates using the Location it gets back.
If what you actually want is to send a user from your application into Lightning Payroll already signed in, use the session handoff instead. That is the supported path, it works whether or not the user has a live session, and it lands them on the selected company's Pays screen. See the Partner Session Handoff Guide.
08Common 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 |
09Integration checklist
Treat this as a UI deep-link helper, not a data API.
Only call it from something that can set an Authorization header. A plain browser link returns 401.
Expect an HTTP 302, not JSON.
Do not prefetch it, because it changes selected-company state.
Use the OAuth guides for authentication and token management; use this route only after authentication is already solved.
To deep-link a user in from your own app, use the Partner Session Handoff Guide rather than this endpoint.