Signing In with a One-Time Access Token

Signing In With Token

This authentication flow is used when embedding WorkBright within another application through an iframe, allowing users to be automatically authenticated and the iframe to load without requiring a separate login.

WorkBright provides separate authentication endpoints for administrators and employees to ensure the correct session management method is used for each experience.

Authentication Endpoints

Generating an Access Token

Before signing a user in, generate a temporary access token using the appropriate token endpoint for the user type.

The access token is then appended to the sign-in URL as a query parameter:

?token={access_token}

Access tokens should be treated as temporary credentials and generated immediately before use. If an access token is not used within 30 minutes of being generated, it will be invalidated. After it is used to sign in, the access token is also invalidated and cannot be used again.

Administrator Authentication

Administrators can sign in with either method:

• Cookie method: /sign_in_with_token (the original endpoint)
• HTTP header method (beta): /embedded/new_sign_in

Cookie Method Example

https://{subdomain}.workbright.com/sign_in_with_token?token={access_token}

Session Behavior

This endpoint uses third-party browser cookies to maintain the authenticated session.

Browser Compatibility

Some browsers, particularly Safari, may block third-party cookies by default. When this occurs, embedded administrator sessions may not persist correctly.

Administrator Redirect Behavior

For administrator sessions authenticated via /sign_in_with_token, navigation within the embedded WorkBright frame is handled using standard JavaScript rather than the postMessage API. Any post-authentication routing should be performed directly within the embedded session.

Administrators authenticated via /embedded/new_sign_in must use the postMessage API instead. See Redirecting After Authentication.

Employee Authentication

Employees should use the newer employee-specific endpoint.

Example

https://{subdomain}.workbright.com/embedded/new_sign_in?token={access_token}

Session Behavior

This endpoint uses HTTP headers instead of browser cookies to maintain the authenticated session.

Because it does not rely on third-party cookies, it works consistently across browsers.

Administrator Authentication with HTTP Headers (Beta)

Administrators can use the same /embedded/new_sign_in endpoint as employees. The session then behaves like an employee session: it uses HTTP headers instead of cookies, so it works in Safari and other browsers that block third-party cookies.

Example

https://{subdomain}.workbright.com/embedded/new_sign_in?token={access_token}

Navigation

Administrators signed in with this method must navigate using the postMessage API, the same as employees. Standard JavaScript navigation from the cookie method does not apply. See Redirecting After Authentication.

Redirecting After Authentication

After an employee, or an administrator using the HTTP header method (beta), has been authenticated using /embedded/new_sign_in, your application can navigate the embedded WorkBright session by sending a postMessage event to the WorkBright child window.

Message Format

Send the following payload to the embedded window as a postMessage API:

{
  "message_key": "load.page",
  "message_data": {
    "href": "/forms/i9/submission/new"
  }
}

Example

const iframe = document.getElementsByClassName("embedded-iframe")[0];
iframe.contentWindow.postMessage(
  {
    message_key: "load.page",
    message_data: {
      href: "/forms/i9/submission/new"
    }
  },
  "*"
);

Redirect Paths

The href value should be a relative WorkBright path.

Example:

/forms/i9/submission/new

The requested page will load inside the existing authenticated session.