Create an embedded session

​

Creates a 60-minute browser session for one authenticated Employer user. Calling this operation confirms that the Partner currently allows the user to access payroll for the Employer.

Provide:

  • A stable partnerUserId for the signed-in user.
  • The user's current displayName.
  • The exact browser origin where you will mount PayrollKit. It must be registered during Partner setup and use HTTPS in production; a loopback HTTP origin may be registered for local development.

The session gives the user access to every supported payroll view for this Employer. It does not contain view-level permissions or choose the first view. Choose an optional initialView when mounting the component. See the Embedded component reference for mounting, navigation and replacement behaviour.

Each browser tab and full page load must receive its own session. One token supports one mounted component at a time, so each component mounted simultaneously needs a separate session. React rerenders do not require another session.

Use the response as follows:

  • Pass sessionToken directly to the page that mounts PayrollKit and keep it only in memory. Never put it in a URL, browser storage, analytics or logs.
  • Retain id on your server until the session expires or its revocation is confirmed.
  • Use expiresAt to replace the session before it expires when the component must remain mounted.

To keep a mounted component active, create a replacement for the same Employer, user and origin with a new Idempotency-Key, then pass its token to replaceSession(). PayrollKit switches sessions without remounting and revokes the previous token. Create a separate session when switching Employer.

An idempotent retry returns the original session response even if its token has since expired or been revoked. Use a new key to create another session.

OAuth scopes
  • embedded:write

Path Parameters

  • employerId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    PayrollKit Employer ID.

Headers

  • Idempotency-Key
    Type: string
    min length:  
    16
    max length:  
    200
    required

    Identifies one write for safe retries. Reuse it only for the same method, URL, content type and body and, when present, the same If-Match value and acting-user headers. PayrollKit retains the result for 30 days, then treats a request using the same key as new.

  • X-Request-Id
    Type: stringFormat: uuid

    Client-generated UUID for tracing. This does not make retries safe.

Body

required
application/json
  • displayName
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Current user name recorded with actions performed through this session. A later session may supply a new name for the same partnerUserId; earlier action records keep the name recorded at the time.

  • origin
    Type: string
    max length:  
    2048    Format: uri
    required

    Exact browser origin where the Partner will mount the component, containing only scheme, host and optional port. It must match an origin registered for the Partner. Production origins use HTTPS; a loopback HTTP origin may be registered for local development.

  • partnerUserId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Stable, case-sensitive ID for the signed-in user in the Partner product. Use the same value for that user across every Employer they can access. It must identify only one user within the Partner account and cannot be changed.

Responses

  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
post/employers/{employerId}/embedded-sessions
Short-lived component session
{
  "id": "embedded_session_6a42f1d8",
  "sessionToken": "embed_session_demo_4f82b6d1c7e93a65",
  "expiresAt": "2026-08-27T17:00:00Z"
}

Embedded session created