Partner Embed Guide

Building, testing, and launching an embedded WorkBright integration

For WorkBright embedded partners Audience: partner engineering, product, implementation, and support teams Developer reference Partnership Hub

Contents

Orientation

1.About This Guide
2.The Embedded Partnership
3.Scoping
4.Integration Decisions

Build

5.Account Structure and Reference Architecture
6.Build Checklist
7.Iframe Implementation
8.Testing
9.Launch Readiness

Partner APIs

10.Partner APIs: Provisioning and Usage

Support and reference

11.Partner Support and Escalation
12.Troubleshooting
13.Glossary

Orientation

1.About This Guide

This guide covers everything your team needs to embed WorkBright inside your product, from the first scoping conversation through launch and ongoing operation. It is written with your engineering, product, implementation, and support teams in mind, though anyone on your side working on the partnership should find it useful.

It assumes the embedded partnership model, covering both the administrative and the employee I-9 and E-Verify workflows running natively inside your application. If your integration is API-only or you are reselling a WorkBright-managed service, your WorkBright contact will point you to the right material instead.

1.1How to use it

Your team	Start here
Product / program lead	Sections 2, 3, 4, then 9
Engineering	Sections 5, 6, 7, 10
QA	Sections 6 and 8
Implementation	Sections 9 and 10
Support	Sections 11 and 12

1.2What you will also receive

Partner Embed Test Plan workbook. A spreadsheet of test cases mapped to the phases in Section 6, with a results summary that rolls up automatically. Your WorkBright contact provides a copy configured for your integration.
Developer documentation. Live API and embed reference at developers.workbright.com.
Testing simulators. A Document Verification simulator and an E-Verify simulator can be enabled on your test environment, so you can exercise both flows end to end without real documents or real federal cases.
A named Customer Success Manager. Your implementation owner. The CSM runs the engagement end to end, from scoping through launch, and is your primary point of contact.
A Solutions Architect. Available for technical consultation on product strategy, architecture, integration design, and the harder judgment calls.

Orientation

2.The Embedded Partnership

The embedded model puts WorkBright inside your product, under your brand, in your workflow. Your customers complete I-9 and E-Verify without leaving your application. It gives you the most control of any WorkBright partnership model, and it carries the most commitment.

This section states those commitments plainly, before you build. Nothing here should be a surprise later.

2.1What you own

Area	What it means in practice
The build	Your engineering team builds against the token, iframe, postMessage, webhook, and REST API surfaces described in Sections 5 through 7. WorkBright acts as a consultant and trusted guide throughout, reviewing your approach and unblocking you.
The user experience	Where the embed appears in your product, how users reach it, and how your UI responds to the events the embed emits.
Tier 1 support	Your customers contact you first. Your support team is the front line for the embedded experience, including day-to-day compliance questions about I-9 and E-Verify. WorkBright supports you behind that line rather than alongside it.
Training	WorkBright trains your teams and you train your customers on the embedded workflow, using material you own.
Account provisioning	If you use the cloning API (Section 10), you own the provisioning calls and the handling of their outcomes.
End-user notifications	In an embedded integration these are always yours. WorkBright does not message your end users directly, so you own every trigger, including re-engagement prompts. See Section 4.
Timeline	The integration timeline is shaped by your embedded strategy, how deep the integration goes, and your engineering availability. Those three together are the largest driver of time to launch.

2.2What WorkBright owns

Area	What it means in practice
The compliance product	I-9 form logic, E-Verify case handling, document verification, retention behavior. This is the part you are embedding and we keep it correct.
The embed surfaces	Token issuance, sign-in endpoints, the embedded application, postMessage events, webhooks, and the REST API.
Implementation	Your Customer Success Manager owns the engagement end to end: scoping, configuration, sequencing, and launch, supported by consultation from a Solutions Architect. The CSM is your primary contact.
Template configuration	Your CSM configures the template accounts your new subdomains inherit from.
Technical consultation	A Solutions Architect for architecture, integration design, and technical judgment calls. Engaged through your CSM.
Tier 2 support	Escalations from your support team, per Section 11.
Platform status communications	Maintenance windows and incident notices sent to your named recipients. These go to your team, not to your end users.

2.3What neither of us owns by default

Compliance obligation sits with the employer of record. That is usually your customer, not you and not WorkBright. Two specific obligations are worth naming now because they surface late otherwise:

E-Verify MOU. Participation in E-Verify is governed by a Memorandum of Understanding signed by the employer. Embedding WorkBright does not transfer that obligation to you or to us.
I-9 retention. Federal retention requirements attach to the employer, and they do not lapse because a platform is no longer in use.

If your model involves you acting as employer of record, or if it is unclear who does, raise it during scoping. It may alter both your integration approach and how you interact with your customers.

Orientation

3.Scoping

Before any build starts, we run a scoping session together. Its purpose is to understand your product and your customers well enough to recommend the right integration shape, rather than having you pick one from a menu and discover the mismatch during testing. It is also a chance to shape your product strategy for the embed: where compliance fits in your roadmap, what you want to be able to tell customers, and which capabilities are worth sequencing early.

This section tells you what we will ask, so you can bring the right people and have the answers ready. A well-prepared scoping session typically removes weeks from the build.

3.1Who to bring

A product owner who can speak to the customer workflow and where onboarding sits within it
An engineer who can speak to your integration capacity and constraints
Someone who can speak to your support model
If compliance ownership is unclear in your model, whoever can resolve it

3.2What we will cover

Your product strategy

What does embedding compliance let you offer that you cannot offer today?
How do you want customers to perceive it: an integrated capability you own, a partner service, or something in between?
Is this a differentiator you plan to lead with, or a requirement you need to satisfy?
What does the embedded experience look like a year from now, and does the shape we pick now leave room for that?
Do you have a specific target date for a desired initial customer launch?

Your customer workflow

Where does onboarding sit in your product, and where does a user start and finish?
Is I-9 a step inside a larger flow you own, or a destination of its own?
What does the user see immediately before and immediately after?

Who uses it

Employee-side, admin-side, or both?
Do your own staff need admin access, or only your customers' HR teams?

Employee-only embeds are meaningfully simpler to build and to support. If admin access is not clearly needed on day one, deferring it is usually the faster path to launch.

Compliance

Who is the employer of record for the workers being onboarded?
Who signs the E-Verify MOU and handles Tentative Non-confirmation decisions?
Are there existing I-9 records, and where do they live today?
How many EINs does the customer operate, and how many E-Verify accounts do they hold? This decides their subdomain structure. See Section 5.2.
Do they need restricted admin access, so that admins only see their own employees? It is enabled per account, so confirm it is available before designing around it. See Section 5.3.

Engineering

Is there a named team and a roadmap slot for this work?
Have they integrated third-party embeds or signed-token auth flows before?

Branding and control

Does the embedded experience need to match your product visually?
What degree of control do you need over navigation inside the embed? There are limits on what can be suppressed or re-routed from outside the frame, so raise it during scoping rather than assuming. See Section 7.4.

Data and identity

Where in your system is the employee record created, and what event triggers the corresponding record in WorkBright?
How will accounts be provisioned, manually or programmatically?

3.3What comes out of it

A recommended integration shape with the reasoning behind it
The decisions in Section 4, recorded
A test plan workbook configured for your integration
A build sequence and a realistic timeline

Orientation

4.Integration Decisions

These are the decisions that shape the build. Work through them with your CSM and Solutions Architect on the WorkBright side, and record the answers. Each one has consequences downstream in testing and launch, and each one is more expensive to change later than to decide now.

Decision	Options	What to consider
Account structure	One subdomain / one per EIN	Follows from the customer’s E-Verify structure rather than preference. One E-Verify account means one subdomain with groups and permissions doing the segmenting. Multiple E-Verify accounts mean one subdomain per EIN, unconnected. See Section 5.2.
Embed context	Website / Mobile app webview / Both	Mobile webviews change camera and geolocation permission behavior and complicate cookie access. Treat a webview as a separate configuration to build and test, not a variation of the web embed. See Embedded WorkBright: mobile configuration.
Auth endpoint	Determined by user type	Admin and employee sign-in use different endpoints and different session mechanics. This is not a preference. See Section 5.6.
Account provisioning	Manual setup / Cloning API	Manual is fine for a handful of accounts. Volume or self-serve signup needs the cloning API in Section 10.
End-user notifications	Partner-owned in every embedded integration	Not a choice in embedded mode. You deliver every end-user message. Two are easy to miss because they sit inside compliance flows rather than at the start of onboarding: WorkBright does not prompt an employee to return and contest a Tentative Non-confirmation, or to complete a new I-9 after one is rejected. Both have compliance timing attached, so build those triggers off the webhook events and treat them as launch scope.
E-Verify configuration	Live / Demo mode	Demo mode in every non-production environment, without exception. Live E-Verify in a test account creates real federal cases under a real MOU.
Document verification	Enabled / Disabled	Affects the employee flow, the failure and retry states you need to handle, and your document capture test cases. A simulator is available for testing.
Authorized representative	Enabled / Disabled	Enabled by setting the i9_remote_countersign_authorized attribute on the create-employee payload. The employee finishes their submission and is taken straight into the representative step, and the representative receives a text message with a countersign link. There is no representative-facing email, and none is needed.
Custom application theming	Default / Custom	Worth doing, not worth delaying launch for. Treat it as a fast follow.

Build

5.Account Structure and Reference Architecture

Two things to establish before any code: how many WorkBright accounts a customer needs, and what your integration connects to once they exist. The first is decided by the customer’s E-Verify structure rather than by preference, and getting it wrong is expensive to unwind after go-live.

5.1Multi-tenancy and isolation

WorkBright runs a multi-tenant PostgreSQL database in which every subdomain is an isolated schema. The subdomain is the unit of tenancy, and your integration connects to each one individually. Nothing crosses a schema boundary. That is what keeps one customer’s I-9 records unreachable from another’s, and it is also why several things you might reasonably expect to work across accounts do not.

What isolation means for your integration

What isolation means	Consequence for your integration
Credentials	Each subdomain has its own API key. Store them per subdomain and route every call to the right host.
Access tokens	Subdomain-scoped. A token minted for one subdomain will not open another.
Admin users	Per subdomain. Someone who administers three EINs needs three admin users, one in each. See Section 6.6 for why that matters to the audit trail.
Company profile and E-Verify credentials	Configured per subdomain, and not inherited when an account is cloned. See Section 10.8.
Cross-subdomain views	There are none. No consolidated dashboard, no cross-schema query, no single endpoint for onboarding progress across accounts. Build it from per-subdomain calls if a customer needs one.
Custom forms	Each subdomain holds its own copy, so form IDs differ and editing one does not change the others.
Usage reporting	The exception. One call returns per-account figures across every subdomain in your partner bundle. See Section 10.12.

Usage reporting is the exception. One call returns per-account figures across every subdomain in your partner bundle. See Section 10.12.

5.2How many subdomains a customer needs

WorkBright holds one E-Verify Company ID and one set of Web Services credentials per subdomain. That single fact decides the structure: the number of E-Verify company accounts a customer holds is the number of subdomains they need. It is not a matter of size, org chart or preference.

Two terms from E-Verify

Verification location — where your staff take the Form I-9 information and create the E-Verify case.
Hiring site — where the employer hires employees and they complete Form I-9. A location can be both.

These are E-Verify’s own terms, not WorkBright’s. Which structure applies depends on how many verification locations the customer holds, not how many hiring sites.

	Scenario A: one verification location	Scenario B: multiple verification locations
Trigger	The organization verifies every hire under a single E-Verify company account.	Each entity or verification location holds its own E-Verify Company ID and Web Services credentials.
Structure	One subdomain, one set of E-Verify credentials.	One subdomain per entity or verification location.
Case routing	Every I-9 countersigned anywhere in the organization opens a case under the same Company ID. There is nothing to select and nothing to route.	Credentials are configured per subdomain, so each site’s cases open under that site’s Company ID automatically. There is no per-case routing to get wrong.
Worksites	Set up as employee groups. An admin scoped to one or more groups sees only those employees, their I-9s and their E-Verify cases, including Further Action Notices and case actions.	Each verification location is its own subdomain. Separation is absolute: employees, I-9s, forms, settings and admin permissions do not cross between them.
The full picture	Corporate admins with no group scope keep one employee list, one E-Verify dashboard and one set of reports.	Reporting runs per subdomain. An organization-wide roll-up is assembled outside WorkBright.
Admins across sites	One login, scoped by group.	One login with access to each subdomain, switching between them.
Employees moving	Keep their record and case history.	Do not transfer between subdomains.

5.3Groups and permission policies

A group is a named label you apply to employees. In an embedded I-9 workflow groups do one job: they define which employees each of your admins is allowed to work with. You create the groups, decide who belongs to each, and give every restricted admin a list of the groups they are responsible for.

Role	What groups do for this role
Full administrator	Nothing. A full admin works across the whole account and groups do not limit them.
Restricted administrator	Everything. They can only work with employees who share at least one group with them, and you set the permissions per group.
Employee	Nothing they can act on. Employees never see the group list and cannot change their own groups.

Groups are a flat list. There are no sub-groups or parent groups; if you need a hierarchy, put it in the name, for example "Northeast – Worksite 12". Groups belong to one account, so names, membership and group ids are never shared between WorkBright accounts. An employee can be in many groups at once, with no limit and no concept of a primary group.

How access is decided

WorkBright compares the groups on the admin against the groups on the employee. The overlap between those two lists is what the decision rests on.

No shared group means group permissions do not apply. When there is no overlap the admin’s group-specific permissions are set aside and their general permissions decide. Group permissions can narrow access, never widen it.

Every shared group has to agree. When an admin and an employee share more than one group, the action has to be permitted for all of them. If any shared group withholds it, the action is withheld. Adding an employee to an extra group can therefore reduce what an admin can do with that record, which is the opposite of what most people expect.

The same rules drive the interface, so an action an admin cannot take is hidden or disabled rather than failing after the fact.

Setting it up

Step	What you do
1. Create the groups	Decide how you want to divide the workforce for access purposes, then create one group per division.
2. Put employees in groups	Assign each employee to the groups that describe them, in the interface or through the API as you create the employee.
3. Scope each admin	Give every restricted admin their list of groups, and set what they may do within each one.

Creating, renaming and deleting

Action	What happens	Where
Create	Available immediately. Empty until you add people, and not part of any admin’s scope until you add it there.	Interface or API
Rename	Membership and admin scopes are unaffected. If you load rosters on a schedule and those files reference the group by name, update the file to match.	Interface or API
Delete	Membership is removed permanently and the group disappears from every admin scope that referenced it. This cannot be undone, so confirm which admins rely on it first.	Interface only

Through the API

Groups, employee membership and admin scope are all available through the API. Requests go to the account’s own subdomain.

Endpoint	Purpose
GET /api/employee_groups	List the account’s groups.
POST /api/employee_groups	Create a group.
PATCH /api/employee_groups/:id	Rename a group.
POST /api/employees/:id/groups	Add the employee to one group.
POST /api/employees/:id/groups/bulk_create	Add the employee to several groups in one request.
DELETE /api/employees/:id/groups/:group_id	Remove the employee from a group.
GET /api/managed_access_policies	List the permission policies you can assign.
POST /api/admins	Create an admin.
PATCH /api/admins/:id	Change an admin’s role, policy or group list.
DELETE /api/admins/:id	Remove an admin.

Working with the API	What to know
Creating a restricted admin	Needs both a policy and a group list. Send the policy as a policy id and the groups as an array of group ids. Both are required for a restricted admin and neither is accepted for a full admin.
Duplicate group membership	Adding an employee to a group they already belong to is rejected rather than silently duplicated, so a retry after a timeout is safe.
Identifiers	Group ids and policy ids are unique within an account only. Do not treat them as globally unique across accounts.
Timing	Group and scope changes take effect immediately. Very large changes are accepted right away and applied in the background.

Restricted admin access is not switched on by default. It has to be enabled on the customer’s account, and where it is not, the option to create a restricted admin does not appear at all. Every admin then sees every employee. Confirm availability with your CSM during scoping rather than at build time.

5.4Integration surfaces

Figure 4. The five surfaces between your product and a WorkBright subdomain.

A WorkBright embed has five surfaces. Most integration problems trace back to one of them being misunderstood, so it is worth reading this section before writing code even if the individual pieces look familiar.

Surface	Direction	What it carries
One-time access token	You to WorkBright	Authentication. You generate a signed token and exchange it for a session.
Embedded iframe	WorkBright into your UI	The rendered WorkBright experience, employee or admin.
postMessage	WorkBright to your page	In-flow events your page reacts to.
Webhooks	WorkBright to your backend	Asynchronous state changes, such as `employee.submission_countersigned`. The full list is at webhook events.
REST API	You to WorkBright	Employee creation, data reads, pagination.

5.5Authentication flow

Figure 5. Token handoff, from generation to a rendered view.

Your backend generates a one-time access token, signed with the credentials issued for the subdomain.
You point the iframe at the appropriate sign-in endpoint with the token.
WorkBright validates the token, establishes a session, and renders the requested view.
The token is consumed. It cannot be replayed, and it expires.

Three properties matter for your implementation and each has a test case in the Foundation phase: expiry, single-use enforcement, and correct rejection of a malformed token. The endpoint reference is Signing In with a One-Time Access Token.

5.6The two sign-in endpoints

There are two endpoints and they are not interchangeable. Choose by user type.

	Admin	Employee
Endpoint	/sign_in_with_token	/embedded/new_sign_in
Session mechanism	Cookies	HTTP headers
Affected by third-party cookie blocking	Yes	No
Typical user	HR admin or your staff working inside your product	A worker completing I-9 Section 1, documents, and identity verification

Both paths are relative to the WorkBright subdomain for the account. The admin path is the one exposed to Safari's third-party cookie blocking and to partitioned storage in mobile webviews, so test it early on those targets. Section 12 covers what to check when it fails.

5.7postMessage

The embedded application emits events on the postMessage channel. Your parent page listens for them and reacts. This is how you respond to progress inside the embed, since cross-origin policy prevents your page from reading the iframe DOM.

Validate the message origin on every event you receive. An unvalidated listener accepts messages from any frame on the page.
Attach the listener before the frame loads, or you will miss early events.
Check the postMessage API reference for the current event list. Events are added over time; treat the documentation as authoritative over any list in this guide. For the browser API itself, see MDN: Window.postMessage().

5.8Webhooks

Webhooks deliver asynchronous outcomes to your backend. Because you own end-user notifications in an embedded integration, they are also what your notification logic runs on.

Configure endpoints per environment. Pointing production at a staging endpoint after cutover is the most common quiet failure we see.
Verify delivery during testing rather than assuming it. There is a Foundation test case for this.
Handle failure outcomes, not just success. A webhook that reports a failed operation still needs a code path.

5.9REST API

Employee creation, including the authorized representative attribute where that flow is in scope.
Record reads for status display and reporting on your side.
Cursor-based (keyset) pagination on the employee endpoint. Use the cursor rather than offset paging for anything large; offset paging degrades and can skip records under concurrent writes.
Rate limits apply. Current limits are documented at developers.workbright.com/docs/rate-limits. Check them before building anything that iterates large record sets.

API basics, including the API-Key header and subdomain conventions, are covered in Getting Started and Authentication.

Build

6.Build Checklist

The build is organized in four phases. Foundation is a prerequisite for everything else: authentication and iframe rendering have to work before any workflow is worth testing. Go-Live items are required to launch. Recommended and Optional items are deliberately not launch blockers, and treating them as such is a common way to delay a launch for no compliance benefit.

These phases match the tabs in your test plan workbook, so checklist items map directly onto test cases.

6.1Foundation

Area	Item
Auth	One-time access token generated server side
Auth	Token expiry handled
Auth	Fresh token generated per sign-in; no reuse of a consumed token
Auth	Admin sign-in via the cookie-based endpoint
Auth	Employee sign-in via the header-based endpoint
Iframe	Iframe renders inside your application shell
Iframe	Sandbox attribute set with the required token set
Iframe	Height and scroll behavior acceptable across your target viewports
Browser	Verified across your target browsers and contexts: Chrome, Firefox, Safari including the storage access sequence on the admin path, and mobile webview where in scope
Permissions	Camera permission granted via the allow attribute and document capture functional
Permissions	Geolocation permission granted via the allow attribute where required
Events	postMessage events received by your parent page
Events	Message origin validated on every event
Webhooks	Endpoint configured and delivery confirmed, per environment
API	API key scoped to the correct account
API	Rate limit responses handled with backoff

6.2Go-Live (required)

The workflows a real customer will exercise on day one.

The Risk column states what is exposed if an item is not supported in the build. Compliance risks affect the employer’s federal obligations and cannot be recovered by fixing the software afterward. Experience risks affect completion rates and support load. The compliance entries are why this phase has no optional items.

Area	Item	Risk if not supported
Employee	Employee record created via API with correct attributes	Compliance and experience. Wrong or missing attributes route the worker into the wrong flow. E-Verify behavior and the authorized representative path both depend on them.
Employee	I-9 Section 1 completion inside the embed	Compliance. Section 1 is due no later than the worker’s first day.
Employee	Authorized representative flow where enabled	Compliance. Remote hires depend on a representative completing Section 2 in person. Not wiring this up means remote onboarding cannot be completed at all.
Employee	Employee-facing error and blocked states render correctly inside the iframe	Experience. A silent failure inside an iframe reads as your product being broken. Workers abandon the flow and call your support team instead of retrying.
Admin	Admin I-9 review and countersignature	Compliance. Section 2 is not complete until it is countersigned. Uncountersigned I-9s are among the most common findings in an audit.
Admin	Admin dashboard renders record status	Experience, with a compliance consequence. Admins cannot see what needs attention, so deadlines pass unnoticed rather than being missed deliberately.
Admin	Admin filters return the expected result sets	Compliance. Filters are how admins find work that is due.
E-Verify	Case creation on I-9 completion	Compliance. Cases are due within three business days of the start date. Missed or delayed creation is an MOU violation attributable to the employer.
E-Verify	Case status visible to the admin	Compliance. Case actions run on federal clocks. Status that is not visible, or not accurate, means the window closes without anyone acting.
E-Verify	Tentative Non-confirmation path, including the employee contest decision	Compliance. The worker has a defined window to contest. Blocking or delaying that decision can result in unlawful adverse action being taken against the worker.
E-Verify	Case Actions	Compliance. Cases left open distort the record and violate the MOU. The closure reason also determines what the employer may lawfully do next.
Compliance	Reverification workflow	Compliance. Expiring work authorization has to be reverified before it lapses. Missing it means continuing to employ someone without valid authorization on file.
Compliance	Rehire workflow	Compliance. Rehires have specific rules on when an existing I-9 may be reused and when a new one is required.
Notifications	End-user notification triggers implemented on your side	Compliance and experience. WorkBright does not message your end users in an embedded integration. Anything you do not send is not sent. Workers stall silently and nobody is watching the clock.
Notifications	Re-engagement triggers implemented for Tentative Non-confirmation, I-9 resubmissions, and rejected I-9	Compliance. WorkBright does not send these. If you do not, a worker in TNC never learns they need to act and the contest window expires.

6.3Recommended

Recommended items are not launch blockers. The risks below are real, but they accumulate over time rather than landing on day one, and none of them create a compliance exposure at launch.

Area	Item	Risk if not supported
Branding	Custom application theming applied	Experience. An unbranded surface appearing mid-flow reads as a handoff to an unknown third party, at exactly the moment workers are asked for identity documents. Drop-off rises.
Admin	Bulk actions on the admin I-9 list	Experience. Admins process records one at a time. Correct but slow, and it becomes a real complaint above a few hundred hires per season.
Admin	Admin notification preferences configured	Experience, drifting into compliance over time. Admins get too much or too little. Alert fatigue means genuine action-required notices get ignored alongside the noise.
Reporting	Standard reports validated against your expectations	Experience. Allows for pre-built reports to be made in each customer account based on the template.

6.4Optional and post-launch

None of these carry compliance exposure. The risks are operational and mostly show up at scale, which is why they sit here rather than in the phases above.

Area	Item	Risk if not supported
Structure	Groups	Experience. Every admin sees every employee unless groups are established and administrative users have scoped permissions. Groups also decide which document packets a worker receives, so this is typically required for enterprise or high-volume clientele. See Section 5.3.
Reporting	Custom reports	Experience. Admins export and manipulate data by hand to answer questions the standard reports do not cover. WorkBright can work with you to create meaningful reports that are applicable to your customer base.

6.5Feature reference

Specifications for each feature named in the phases above, grouped the same way. Where a feature is reached by embedding a path, that path is labelled Embed path in the table below. Embed paths are relative to the customer’s WorkBright subdomain, so /forms/tnc resolves to https://{customer-subdomain}.workbright.com/forms/tnc.

A feature with no embed path listed is either driven through the API or has no separately embeddable route. Check with your CSM before assuming a path exists.

The Supported in column matters for scoping. UI means the feature is reached by embedding the path. API and UI means you can either embed it or drive it programmatically, which is usually the better choice where the action originates in your product rather than in the WorkBright interface.

Go-live: employee workflows

Feature	What it does, and its embed path	Supported in
I-9 Section 1 and supporting documentation	Employees complete Section 1 of Form I-9 and upload the identity and work authorization documents required by USCIS. Embed path `/forms/i9/submission/new`	UI
Tentative Non-confirmation (TNC)	Notifies employees of a TNC result returned by E-Verify and walks them through the resolution workflow. Embed path `/forms/tnc`	UI
I-9 resubmission	Employees resubmit a corrected or updated Form I-9 when an admin requests changes.	UI
Remote reverification	Employees complete reverification of expiring work authorization documents remotely, without an in-person meeting.	UI

Go-live: admin workflows

Feature	What it does, and its embed path	Supported in
Employee creation and I-9 ordering	Admins or integrated systems create employee records and trigger the I-9 workflow.	API
Supplement B	Admins complete Supplement B for reverification and rehire scenarios. Embed path `/staff/{employeeID}/submissions/{submissionID}`	UI
Approve or reject I-9 submission	Admins review submitted I-9s and either approve them or send them back for correction. Embed path `/staff/{employeeID}/submissions/{submissionID}`	API and UI
Request new I-9 submission	Admins request a fresh I-9 submission when updates or corrections are needed. Embed path `/staff/{employeeID}/forms`	API and UI
Request remote reverification	Admins initiate a remote reverification request for employees with expiring documents. Embed path `/staff/{employeeID}/submissions/{submissionID}`	API and UI
Admin countersignature	Admins electronically countersign completed Form I-9 records. Embed path `/onboarding/i9/review?ids[]={submissionID}`	UI
Unsubmitted receipts	Track and manage employees who submitted receipt documentation in place of final documents, and prompt action when the finals are due. Embed path `/onboarding/i9/index?filter=reverify&status=all`	API and UI
Awaiting SSN	Manage employees who have not yet received a Social Security Number, so their I-9 and E-Verify case can be completed once it arrives. Embed path `/onboarding/i9/index?filter=awaiting_ssn&status=all`	API and UI
Additional information notes on Form I-9	Admins add compliance notes directly to a Form I-9 record. Embed path `/onboarding/i9/review?ids[]={submissionID}&edit=true`	UI
Review and act on E-Verify cases	Admins review E-Verify case statuses and take any follow-up action required to resolve them. Embed path `/everify/cases/{id}`	UI
Admin creation	Create and manage administrator accounts and their permissions. Embed path `/admin/admin_users`	API and UI
Edit I-9 Section 2	Admins correct or update Section 2 information on a Form I-9 when necessary. Embed path `/onboarding/i9/review?ids[]={submissionID}&edit=true`	UI

Go-live: configuration

Feature What it does, and its embed path Supported in

Feature	What it does, and its embed path	Supported in
E-Verify credential configuration	Configure the customer's E-Verify credentials so cases can be submitted on their behalf. Embed path `/admin/everify/accounts`	API and UI
Company profile configuration	Set company-level onboarding, compliance, and workflow defaults. Embed path `/admin/company/edit`	API and UI

E-Verify credential configuration

Configure the customer's E-Verify credentials so cases can be submitted on their behalf.

Embed path /admin/everify/accounts

API and UI

Company profile configuration

Set company-level onboarding, compliance, and workflow defaults.

Embed path /admin/company/edit

API and UI

Both configuration items are per-account and are covered as provisioning steps in Section 10.8.

Go-live: notifications

Feature	What it does, and its embed path	Supported in
Staff notifications	Notify staff about onboarding tasks, compliance workflows, and required actions.	Partner-owned

Recommended before launch

Feature	What it does, and its embed path	Supported in
Review document verification results	Admins view document verification statuses and outcomes after submissions are processed. Embed path `/staff/{employeeID}/submissions/{submissionID}`	API and UI
Work authorization extensions	Track and manage employees whose work authorization has been extended, for example automatic EAD extensions. Embed path `/onboarding/i9/index?filter=reverify&page=1&sort_dir=asc&sort=name&expiration=all&status=all&document_verification_status=all`	API and UI
Rehire	Process rehire workflows for returning employees. Embed path `/staff/{employeeID}/employment`	API and UI
Termination and deactivation	Terminate or deactivate employee records when employment ends. Embed path `/staff/{employeeID}/employment`	API and UI

Optional and post-launch

Feature	What it does, and its embed path	Supported in
Custom application theming	Customize branding, colors, and styling within the embedded experience to match your product.	API
Groups configuration	Organize employees and admins into groups. Membership also determines document assignment and what a restricted admin can see and act on. See Section 5.3. Embed path `/admin/employee_groups`	API and UI
Reports	Access standard and custom reporting. Not required for compliance, with one exception: monitoring receipt-based documentation workflows. Embed path `/reports`	UI
Admin notifications	Notify admins about workflow updates, pending actions, and compliance events.	Partner-owned

6.6Best practice: admin users and the audit trail

This is the modeling decision partners get wrong most often, and it is expensive to correct after launch because the records already written cannot be reattributed.

Create a WorkBright admin user for each of your customer’s users who will act on I-9 records. One admin per person, not one admin per company, and not a single integration identity that every action runs through.

Why it matters

Every consequential action on a WorkBright record is written to the audit log with an actor attached. The actor is whoever the session belongs to. If your integration signs every user into the same admin account, then the audit log attributes all of it to that one identity.

That is a compliance problem rather than a reporting inconvenience. During an I-9 inspection, the question is who examined the documents and who attested to Section 2. An audit trail that answers "the partner integration" for every record on the account does not evidence what the form asserts, and the countersignature is a personal attestation by the person who did the examining. A shared identity undermines the thing the signature is for.

The same reasoning applies to rejections, requests for a new I-9, Section 2 edits, and case actions on E-Verify. Each is a decision someone made, and the record should say who.

How to model it

Map your users to WorkBright admins one to one. When one of your customer’s users first needs admin access, create a corresponding WorkBright admin for them rather than reusing an existing one.
Generate the one-time access token for that specific admin, so the session and therefore every audit entry it produces carries their identity.
Use the admin creation feature in Section 6.5 to provision them, by API where you are automating onboarding of the customer’s team.
Deactivate admins when someone leaves your customer’s team. Historical audit entries stay attributed correctly; what you are closing is the ability to act.
Remember that admin users are not copied from a template, per Section 10.10, so this is per account rather than something you configure once.

Where a system identity is appropriate

The distinction is between machine actions and human attestations, not between API and UI. Driving employee creation, ordering I-9s, or syncing records with an API credential is correct, and the audit log showing your integration as the actor is accurate in those cases, because your system genuinely did it.

What should not happen is a human decision being recorded as a system action. If a person chose to reject an I-9 or countersign a Section 2, the log should name that person.

Build

7.Iframe Implementation

The markup below is the supported configuration and matches the Embedded iframe reference.

7.1Markup

<iframe
class="embedded-iframe"
width="100%"
height="1200"
frameBorder="0"
allow="geolocation *; camera *"
:src="placeholder"
title="embedded-workbright"
sandbox="allow-scripts allow-same-origin allow-popups allow-forms
allow-storage-access-by-user-activation"
></iframe>

The :src binding is Vue syntax pointing at a runtime variable holding the signed sign-in URL. Adapt it to your framework; the substance is that the URL is resolved at runtime, not hardcoded.

7.2Attributes

Attribute	Value	Purpose
class	embedded-iframe	CSS and JS selector hook. No functional behavior.
width	100%	Spans the containing element. Prefer setting this in CSS.
height	1200	Fixed pixel height. A fixed value gives you either a scrollbar inside the frame or dead space below it, depending on the view. To grow the frame with its content, listen for the postMessage height event and resize from the parent; measuring the frame directly is blocked by cross-origin policy.
frameBorder	0	Removes the default border. The attribute is deprecated; style="border: 0" is the modern equivalent.
allow	geolocation ; camera	Permissions Policy. Required for document capture and any location-gated step. Without it the browser denies the request before the user is ever prompted.
:src	Runtime binding	The signed sign-in URL. If the variable is undefined on first render the iframe loads twice and users see a flash. Guard the render until the URL resolves.
title	embedded-workbright	Accessibility. Screen readers announce it.
sandbox	Token list	Restricts frame capabilities to the listed set.

7.3Sandbox tokens

Token	Effect
allow-scripts	Permits JavaScript execution in the frame.
allow-same-origin	Preserves the frame's normal origin so it can read its own cookies and storage and make same-origin requests.
allow-popups	Permits window.open and target="_blank".
allow-forms	Permits form submission.
allow-storage-access-by-user-activation	Permits the frame to call the Storage Access API following a user gesture.

One note for your security review: allow-scripts combined with allow-same-origin means the framed document could remove its own sandbox attribute when same-origin with the parent, so the sandbox provides limited protection in this configuration. This is expected for a trusted embed, and it is better to raise it in your review than to discover it there.

7.4What is not supported

Not supported	Why
Reading or modifying the iframe DOM	Cross-origin policy prevents it, by design.
Cropping the frame to hide parts of the experience	Wrapper overflow tricks break on any layout change, and in a compliance workflow hiding a required step is a liability rather than a workaround.
Suppressing WorkBright navigation from outside the frame	Where suppression is legitimately needed it is exposed as WorkBright configuration, usually a URL parameter. Ask rather than working around it.

The reasoning behind the last two: what appears in the embed is what the compliance workflow requires. Allowing it to be suppressed from outside would let a required step be removed without anyone intending it. Where you need control, we would rather add a supported configuration than have you build something fragile.

Build

8.Testing

Testing runs from the WorkBright Partner Test Matrix. Open the link and download a copy, or make your own copy in Drive, then adapt it to your integration before you start. Your WorkBright representative can help you scope which cases apply. This section covers how to run it and what has to be true before you move between phases.

8.1Workbook structure

Tab	Contents
Overview	Your integration metadata: model, subdomain, environment, E-Verify mode, notification scope, test owner, date. Fill this in first; the rest of the plan branches on it.
Foundation	Auth, iframe rendering, browser behavior, permissions, postMessage, webhooks, rate limits.
Go-Live Required	Employee, admin, E-Verify, compliance, notification, and session workflows.
Recommended	Application theming, bulk actions, reporting, admin notifications.
Optional	Groups, custom reports, advanced application theming.
Results Summary	Live rollups of pass, fail, blocked, and N/A counts plus percentage pass per phase.

Each case carries a Test ID, Area, Test Case, Preconditions, Steps, Expected Result, Priority, Result, and Notes. Filter on Result to produce a defect list without rekeying anything.

8.2Phase gates

Foundation

Before you start: environment provisioned, API key issued, webhook endpoint configured, and you can generate a token.
Before moving on: all P0 and P1 Foundation cases pass on every target browser and embed context. Do not begin workflow testing until this holds; failures downstream will be auth or rendering problems in disguise.

Go-Live Required

Before you start: Foundation complete. E-Verify in demo mode. Test employee records seeded.
Before launch: all P0 cases pass. Any open P1 has a named owner, a fix date, and a documented workaround. No open P0 at launch.

Recommended and Optional

Before you start: Go-Live phase complete.
Outcome: results recorded. Failures here do not block launch; they become post-launch backlog with dates attached.

8.3Priority definitions

Priority	Definition
P0	Blocks launch. Compliance-incorrect behavior, data loss, or a workflow that cannot be completed.
P1	Significant. The workflow completes but with a workaround, or the defect is visible to end users.
P2	Moderate. Cosmetic or low-frequency, with a clear path around it.
P3	Minor, or an enhancement request.

8.4Test data rules

Test data rule	Why
E-Verify runs in demo mode in every non-production environment	Demo mode is switched on for the subdomain by your WorkBright representative, so request it as part of environment setup. Live E-Verify against a test account creates real federal cases under a real MOU, and that is not recoverable by deleting the test record.
Use dedicated test identities	Do not use real employee data in a sandbox.
Use the simulators	The Document Verification and E-Verify simulators can be enabled on your test environment and let you exercise the full flow, including failure paths, without real documents or real federal cases.
Record the test identity	Note it in the Notes column for any status-related issue. Those are difficult to reproduce without it.

8.5Demo E-Verify behavior

Demo mode is enabled on your subdomain by your WorkBright representative. Once it is on, case outcomes become predictable so you can test each path deliberately instead of waiting to see what a real case returns. The simulated status is driven by the first name of the employee on the I-9 being countersigned.

Target status	How to trigger it	Further action
Closed Authorized	Employee first name starts with A through M	None. The case closes as authorized.
Photo Match	Employee first name starts with N through Z	Confirm the photo as matching to move the case to Closed Authorized. Reject it as not matching to move the case to Tentative Non-confirmation.
Tentative Non-confirmation	Employee first name starts with N through Z, then reject the photo match	Use this to exercise the TNC path, including the contest decision and your re-engagement notification.
Submission Error	Submit the I-9 with a US passport number of 10 or more characters	Resubmit with a valid nine-digit passport number. The case then resolves to Closed Authorized or Photo Match depending on the first name.

These four cover the paths an admin has to act on. They are not the full set of E-Verify statuses. Anything else falls into one of two groups: the case is still processing and there is nothing for the admin to do, or it needs to be reviewed and resolved in the E-Verify dashboard by following the instructions there.

Build

9.Launch Readiness

Launch is a gate, not a date. Everything below should be true before real customer traffic reaches the embed.

Area	Criterion	Owner
Test	All P0 cases pass; open P1s have owner, date, and workaround	You
Test	Results Summary complete and shared with your CSM	You
Environment	Production subdomain provisioned and configured	WorkBright
Environment	Production API key issued and stored securely	Both
Environment	Production webhook endpoints configured and delivery verified against production	You
Compliance	E-Verify configuration confirmed for production, including MOU ownership	Both
Compliance	I-9 retention and record ownership confirmed in writing	Both
Compliance	End-user notification triggers built and verified, including re-engagement	You
Support	Your Tier 1 named, staffed, and reachable	You
Support	Escalation contacts documented on both sides	Both
Support	Your support team has read Section 12	You
Rollback	Rollback path documented and agreed	Both

Partner APIs

10.Partner APIs: Provisioning and Usage

Two APIs sit at the partner level rather than the customer level. They matter if you provision accounts at volume or need to reconcile usage; a partner onboarding customers by hand can skip this section.

Two APIs are scoped to your partner bundle rather than to an individual customer account: subdomain cloning, covered in 10.1 through 10.11, and usage reporting, covered in 10.12. Both are issued against your main partner subdomain using the API key that belongs to it.

If you are provisioning WorkBright accounts at volume, or offering self-serve signup, you can create subdomains programmatically by cloning a template. The new account inherits the template's branding, workflows, document packets, and settings, so there is no manual setup per customer.

10.1How it works

Figure 6. Cloning a subdomain, and what still needs configuring afterward.

As a preliminary step, configure the account.provisioned webhook on your main partner subdomain. Cloning is asynchronous and this webhook is the only signal that an account finished provisioning, so wire it up before your first clone call rather than after.
Your Customer Success Manager provisions one or more template subdomains, configured with the settings new accounts should inherit.
You call the clone endpoint from your main partner subdomain, naming the template in the request body.
You receive an immediate response with status pending, plus the API key for the new account. The account is not usable yet.
When provisioning completes, an account.provisioned webhook fires with a status of succeeded or failed.

10.2Endpoint

Field	Value
Method	POST
Path	/api/partner/accounts/clone
Base URL	https://{your-main-subdomain}.workbright.com
Auth	API-Key header
Content-Type	application/json

Both the endpoint host and the API key are tied to your main partner subdomain. Issue the request against your main subdomain, never against a template subdomain. The template you want to clone is named in the body, not the URL. General API authentication rules are in Authentication.

10.3Body parameters

Field	Type	Required	Description
template	string	Yes	Subdomain of the template account to clone. Your CSM provisions these and will tell you the names.
subdomain	string	Yes	Desired subdomain for the new account. Must be globally unique and URL-safe: lowercase letters, numbers, and hyphens.
name	string	Yes	Human-readable display name for the new account.
account_type	string	No	Set to test to create a sandbox account. Test accounts do not count toward usage and enable a sandbox version of Document Verification. Do not use it for production accounts.

10.4Example request

curl --location 'https://yoursubdomain.workbright.com/api/partner/accounts/clone' \
--header 'API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"template": "templatesubdomain",
"subdomain": "desiredsubdomain",
"name": "Subdomain Name"
}'

10.5Success response

202 Accepted. Cloning is asynchronous. This response confirms the request was accepted, not that the account is ready to use.

{
"subdomain": "desiredsubdomain",
"api_key": "...",
"status": "pending"
}

10.6Errors

Response	Cause	What to do
401 Unauthorized	The API-Key header is missing or wrong	Confirm you are using the key for your main partner subdomain, not a template or child account. The body comes back empty, so there is no field-level detail to read.
422 Unprocessable Entity	The requested subdomain is already in use	Pick a different one. Worth handling programmatically if you derive subdomains from customer names, since collisions are likely.
422 Unprocessable Entity	The subdomain value is not formatted correctly	Use lowercase letters, numbers, and hyphens only. Sanitize before sending rather than relying on the error.

Both 422 cases return errors keyed by field:

{
"errors": {
"subdomain": ["has already been taken"]
}
}

10.7account.provisioned webhook

{
"event_key": "account.provisioned",
"occurred_at": "...",
"data": {
"subdomain": "desiredsubdomain",
"status": "succeeded"
}
}

Handle the failed status as deliberately as the succeeded one. An account left pending that nothing ever checks is a silent onboarding failure: your customer sees a signup that appeared to work and an account that never arrives.

10.8After an account is provisioned

Cloning gets the account created and inheriting the template. Three things still need attention on every new account before it is ready for a real customer.

Step	Why it is needed
Company information	Always required. Legal entity name, address, and related details are specific to the customer and are not inherited from the template.
E-Verify credentials	Always required. E-Verify participation is tied to the employer, so each account needs its own credentials. Cases cannot be created until this is done.
Webhook endpoints	Required where your endpoints differ between customer instances. A cloned account inherits the template configuration, so if a customer needs its own destination, set it before go-live rather than after the first case fires.

Build these into your provisioning flow rather than treating them as manual follow-up. An account that exists but has no E-Verify credentials looks ready and is not.

10.9What a clone copies

Knowing where the template boundary falls is what makes the difference between a provisioning flow that produces usable accounts and one that produces accounts needing manual repair. These carry over from the template:

Forms and documents, including their settings, fields, ordering, and group assignments
Fields, both custom and standard
Employee groups
Saved reports
Feature configuration, meaning which features are enabled
Admin permission settings
Webhook configuration
Embedded redirect URL settings, where the embedded feature is enabled
Conditional logic, where enabled

10.10What a clone does not copy

These do not carry over and are the reason a freshly cloned account is not yet ready for a customer:

Not copied	Consequence for your flow
Company address	Set per account. Covered in Section 10.8.
E-Verify credentials	Set per account. Cases cannot be created until this is done. Covered in Section 10.8.
Submission deadline settings	Whether relative or exact dates, deadlines need configuring per account.
Admin users	Every account starts with no admins. This is more consequential than it looks, and Section 6.6 covers how to model it.
CSS configuration	Custom styling is applied per account rather than inherited.

Three platform limits sit alongside this and are worth knowing before you design around them:

Custom forms are not shared across subdomains. Each cloned account gets its own copy, so a change to a template form does not propagate to accounts already created from it, and form IDs differ between accounts.
There is no single dashboard for viewing activity across child subdomains, and no cross-subdomain endpoint for onboarding progress. If you need a consolidated view, build it on your side from per-account API calls.
There is no de-provisioning endpoint. Accounts cannot be removed programmatically, so avoid creating throwaway production accounts and use account_type test for anything disposable.

10.11Provisioning checklist

Worth running through before your first production clone, and worth encoding as assertions in your provisioning code afterward:

The request goes to your main partner subdomain, not a template
The API key belongs to that main subdomain
The template name matches one your WorkBright representative provisioned
The subdomain is globally unique and uses only lowercase letters, numbers, and hyphens
A display name is set
The returned api_key for the new account is captured and stored securely
The account.provisioned webhook is configured on your main partner subdomain and you are listening for it
Company information, E-Verify credentials, and per-customer webhook endpoints are handled after provisioning
Admin users are created for the account, per Section 6.6

Reference documentation: Partner Subdomain Cloning, Account Provisioned, and the list of webhook events. There is also a step-by-step guide in the Partnership Hub.

10.12Usage reporting

One call returns usage across every subdomain in your partner bundle for a date range, broken out per account. Use it to reconcile against invoices, to bill your own customers where you resell, and to see which accounts are actually active.

Endpoint

Field	Value
Method	GET
Path	/api/license_consumption
Base URL	https://{your-main-subdomain}.workbright.com
Auth	API-Key header
Content-Type	application/json

Query parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start of the reporting period, formatted YYYY-MM-DD.
end_date	string	Yes	End of the reporting period, formatted YYYY-MM-DD.
subdomains	array of strings	No	Limits the report to the named subdomains. Omit it to cover every account in the bundle.

Example request

curl --location --request GET \
'https://yoursubdomain.workbright.com/api/license_consumption?start_date=2026-01-01&end_date=2026-03-31' \
--header 'API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json'

A malformed or missing date range returns 400 Bad Request.

Response fields

Attribute	Type	Description
start_date	string	Start of the reporting period, YYYY-MM-DD.
end_date	string	End of the reporting period, YYYY-MM-DD.
total_usage	integer	Aggregated usage across every subdomain in the report.
accounts	object	Per-account usage summaries, keyed by account identifier. Each key maps to an object holding that account’s I-9 activity for the period. Treat it as a map to iterate, not an array to index.
total	integer	Per account: countersigned I-9s plus rehired I-9s for the period.
countersigned_i9	integer	Per account: countersigned I-9s for the period.
rehired_i9	integer	Per account: rehired I-9s, meaning Supplement B, for the period.

What counts as usage

Usage is countersigned I-9s plus rehired I-9s. Nothing else. This is the most useful thing to understand about the endpoint, because the intuitive assumption is that usage tracks employees created, and it does not.

An employee record created through the API and never completed does not count.
An I-9 sitting in Section 1, or submitted and awaiting review, does not count. Usage is recorded at countersignature, when the employer attestation is complete.
A rehire processed through Supplement B counts, and is reported separately from a fresh countersignature, so you can tell new hires from returning ones.
Accounts created with account_type set to test do not count toward usage at all. See the note in Section 10.3.

Two consequences worth designing around. Reconciling usage against your own records means counting countersignatures rather than onboarding starts, so if your product reports funnel volume those two numbers will legitimately differ. And because usage lands at countersignature, a customer who onboards heavily at the end of a period may see that usage fall into the next one.

Reference documentation: Partner Usage and the Partner Usage Object.

Support and reference

11.Partner Support and Escalation

Two routes, depending on what you need. Integration questions go to your CSM; everything else goes through standard support. Critical incidents bypass both.

11.1Escalating to WorkBright

Integration and technical questions

For anything related to the integration build, configuration, or troubleshooting, contact your CSM directly with the details below. Escalations arriving without them will come back with questions, which costs a cycle.

Account subdomain
The specific test or user identity affected
Browser, version, and embed context (website or webview)
Timestamps, with time zone
Reproduction steps, and whether it reproduces consistently
What your team already checked in Section 12

General support questions

Anything outside the scope of integration build assistance goes through standard support channels at [email protected]. Response times, request types, and critical incident submission are covered in the WorkBright Partnership Support Model.

One exception to both paths

Critical Incidents (security breach or data compromise) and Critical Service Interruptions (large-scale outage or a major feature unavailable) are escalated immediately rather than worked up the tiers in sequence.

Submit a Critical Incident Report and notify your CSM.

11.2Maintenance and incident notifications

Platform availability, planned maintenance windows, and incident history are published at status.workbright.com. Subscribe during onboarding. The developer documentation points to the same page under Availability.

Subscribe your team to status.workbright.com so you see incidents and planned windows without waiting to be told.
WorkBright maintenance windows and incidents are also communicated to your named recipients in advance where planned.
Provide a distribution list, not an individual, during onboarding. Your CSM keeps this list current.
Because the embed lives inside your product, an outage surfaces in your UI, not on a WorkBright page your users would recognize. Plan how you will communicate to your customers during a window.

Support and reference

12.Troubleshooting

Common issues, most of them configuration rather than defects. Work through this before escalating.

Symptom	Likely cause	What to do
Admin embed blank or bounced back to sign-in in Safari	Third-party cookie blocking on the cookie-based admin path	Three conditions all have to hold: the sandbox includes allow-storage-access-by-user-activation, the frame calls document.requestStorageAccess() after a genuine user gesture, and the user has previously visited the subdomain as a first party. That last one is the one teams do not anticipate, and you cannot control it. If all three hold and it still fails, escalate.
Same symptom in a mobile webview	Partitioned storage in the webview	Same checks as Safari. Confirm whether your webview supports the Storage Access API at all before committing to a fix.
Employee embed loads but camera capture fails	Missing camera token in the allow attribute, or OS permission denied	Verify allow="camera *" on the iframe first. The Permissions Policy gate happens before the user is prompted, so a missing token looks like a denied prompt. Then check OS and browser permission state.
Iframe loads twice, visible flash	The src binding is undefined on first render	Guard the iframe render until the signed URL resolves.
Sign-in fails on a second attempt with the same URL	Tokens are single use and one has already been consumed	Generate a fresh token per sign-in. Do not cache the URL.
Sign-in fails intermittently after the page has been open a while	Token expiry	Generate the token at the moment of navigation rather than at page load.
Parent page receives no postMessage events	Listener attached late, or the origin check is rejecting valid messages	Attach the listener before the frame loads. Confirm the expected origin matches the subdomain exactly, including scheme.
Webhooks stopped arriving after go-live	Endpoints still pointed at staging	Reconfigure per environment and re-verify delivery. This is the most common post-cutover issue.
Links inside the embed open a new tab and break context	Structural limitation of the current embedded experience	A structural consequence of a standalone admin application being served in a frame. Report it so it counts toward prioritization rather than building a workaround around it.
WorkBright navigation visible inside your UI	Same structural limitation	Same root cause. You have limited control over navigation routing inside the frame, so ask your CSM whether a supported configuration exists for your case.
Bulk data pull returns partial results or times out	Offset paging, or rate limiting	Use cursor-based pagination on the employee endpoint and handle rate limit responses with backoff.
A record's status looks wrong	Varies	Capture the subdomain, identity, both the dashboard view and the record view, and a timestamp, then escalate. Status issues are hard to reproduce without that detail.

Support and reference

13.Glossary

WorkBright terms first, then the federal ones. The compliance definitions are USCIS and E-Verify’s, not ours.

Term	Definition
Embed / embedded experience	WorkBright rendered inside your application via iframe.
Partner bundle	The grouping under which your partner-owned subdomains are administered.
Template subdomain	An account configured by your CSM whose settings new accounts inherit when cloned.
One-time access token	A single-use, expiring credential you generate to establish a WorkBright session.
postMessage	Browser API for cross-origin messaging between the iframe and your page.
Storage Access API	Browser API allowing an embedded origin to request unpartitioned cookie access after a user gesture.
Keyset pagination	Cursor-based paging on the employee API. Preferred over offset paging for large data sets.
I-9	Federal Employment Eligibility Verification form. Section 1 is completed by the employee, Section 2 by the employer. USCIS: Form I-9
E-Verify	Federal system comparing I-9 information against government records. E-Verify for employers
MOU	Memorandum of Understanding governing E-Verify participation. Held by the employer of record.
TNC	Tentative Non-confirmation. The employee may contest within a federally defined window. E-Verify: Tentative Non-confirmations
FNC	Final Non-confirmation. Carries employment eligibility consequences.
Reverification	Re-confirming work authorization when a document expires.
Countersign	The admin or authorized representative signature completing the I-9.
Authorized representative	A person designated to complete Section 2 in person on the employer's behalf.
Employer of record	The entity legally responsible for the employment relationship, and therefore for I-9 and E-Verify obligations.

13.1Who to ask

Your Customer Success Manager: start here for anything. The CSM owns your implementation, from account configuration and templates through test plan and launch readiness.
A Solutions Architect: architecture and integration design.
WorkBright support: escalations from your Tier 1, per Section 11.1.

13.2Reference links

WorkBright developer documentation

Resource	Link
Developer hub	developers.workbright.com
Getting started	API introduction and conventions
Authentication	API-Key header and auth rules
One-time access token	Signing in with a token
Embedded iframe	Iframe markup and attributes
postMessage API	Event listening from the parent page
Mobile embed	Embedded WorkBright configuration
Partnership Hub	intercom.help/Partner_Hub/en
Platform status	status.workbright.com
Availability policy	Availability and outage reporting

Browser platform references

Topic	Link
Storage Access API	MDN: Storage Access API
Requesting storage access	MDN: Document.requestStorageAccess()
Cross-origin messaging	MDN: Window.postMessage()

Compliance references

Provided for orientation. These are federal sources, not WorkBright guidance, and they do not replace advice from whoever holds the compliance obligation in your model.

Topic	Link
Form I-9	USCIS: Form I-9, Employment Eligibility Verification
I-9 retention and storage	USCIS: Retention and Storage
E-Verify for employers	E-Verify: Employers
Tentative Non-confirmation	E-Verify: Tentative Non-confirmations (mismatches)

Generated from the source document, so this page and the Word version always match. Embed paths are relative to the customer’s WorkBright subdomain.