Iframe Handshake Protocol

When your app loads inside Workrock, it needs a way to prove who it’s talking to and retrieve authentication tokens. We use a standard postMessage handshake.

The Protocol

1. Request Context (WORKROCK_INIT)

Once your app’s DOM is ready, send a message to the parent window:

window.parent.postMessage({ type: 'WORKROCK_INIT' }, '*');

2. Receive Context (WORKROCK_CONTEXT)

Listen for the response from Workrock Core. The payload includes your scoped JWT.

window.addEventListener('message', (event) => {
    // SECURITY: In production, verify event.origin
    if (event.data?.type === 'WORKROCK_CONTEXT') {
        const { access_token, user } = event.data.payload;
        console.log('Logged in as:', user.email);
        // Save the token for future API calls
        localStorage.setItem('workrock_token', access_token);
    }
});

Using the useWorkrock Hook (React)

If you are using React, we provide a convenient hook to handle this automatically:

import { useWorkrock } from '@workrock/sdk';

function MyApp() {
    const { isAuthorized, token, user } = useWorkrock();

    if (!isAuthorized) return <p>Authenticating...</p>;

    return <h1>Hello, {user.name}!</h1>;
}

Token Expiration

The token provided in the handshake has a limited lifespan (usually 1 hour). Your app should handle 401 Unauthorized responses by re-triggering the WORKROCK_INIT handshake to get a fresh token.