--- summary: Agent-facing delivery workflow for provisioning a SigID sandbox, testing with human-shaped fixture accounts, verifying branding, and handing the workspace and agent identity to a developer. tags: - developers - agents - provisioning - testing - handoff - branding categories: - AI Agents --- # Provision, Test, And Hand Off Provisioning is more than creating a client ID. For an agent-built SigID integration, the deliverable is a reproducible developer workspace: identity resources, a working human login path, test personas and application state, and a deliberate ownership transfer. ## What SigID Provisions `sigid-cli setup` creates the SigID-owned substrate: | Resource | Purpose | |---|---| | Agent identity and local signing key | Authenticates the integrating agent | | Sandbox organization | Bounds the pre-production workspace and its limits | | Tenant environment and issuer | Holds login policy, users, branding, and applications | | OAuth application | Supplies the client ID, redirect contract, and optional once-only secret | | Tenant-scoped agent token | Lets the agent manage the sandbox within its scopes | | Fixture human | Exercises the real hosted human authorize path | | Optional operator invitation | Adds a human co-owner, but does not transfer the agent | SigID does **not** provision the integrating application's own sample data. A document, signature request, project, or inbox row lives in that application. The integrating agent must create that data through the application while acting as a fixture human, then record how the developer can reach it. ## The Delivery Sequence ### 1. Provision The Sandbox ```bash sigid-cli setup \ --idp "$SIGID_IDP" \ --name docs-signing-agent \ --redirect-uri http://localhost:3000/auth/callback ``` Capture the non-secret resource identifiers from the result: `agent_id`, `organization_id`, `application_id`, `client_id`, tenant issuer, and tenant ID. The CLI writes the first once-only fixture credential to the gitignored, owner-only `.dev/sandbox-fixture.env` file. ### 2. Prepare The Hosted Experience The tenant Branding studio is at **Dashboard → Branding → Theme**. A human operator can preview changes on every plan after accepting the handoff. Saved hosted-login customization requires the tenant `branding` entitlement; Starter is the first self-serve paid plan that includes it. An agent-only sandbox cannot attach billing, and a sandbox fixture has no Dashboard authority. The agent can prepare the desired values and assets, but must not claim that branding was previewed or saved before a human operator participates. The API shape used by the Dashboard is: ```http PATCH /api/v1/control-plane/tenants/{tenant_id}/config Authorization: Bearer Content-Type: application/json { "config": { "branding": { "app_name": "Acme Sign", "logo_url": "https://cdn.example.com/acme-sign.svg", "theme": { "colors": { "primary": "#2457E6", "primary_hover": "#1946C7" }, "radii": { "scale": "soft", "card": "12px" }, "button_style": "flat" } }, "login_page": { "methods": ["passkey", "password"], "preferred_method": "passkey" } } } ``` Use an absolute `https` logo URL outside local development. Logo URLs accept only `http` or `https`; invalid URLs and unsafe theme values are not rendered. A save without the entitlement returns `402 payment_required` with `feature: "branding"`. The first sandbox authorize test therefore uses default SigID branding. After handoff, the developer can preview the prepared design while the organization is still sandbox-tier. Activation retires all fixture humans. After activation and plan selection, save the branding and repeat authorize testing with a normal invited or self-registered test user, not the retired fixture credentials. ### 3. Test As Human Personas Agent principals manage the integration; they are not human OIDC test users. Bootstrap supplies one ordinary fixture human. Create up to five active fixture humans per sandbox tenant when the application needs multiple roles: ```http POST /api/v1/sandbox/fixture-users Authorization: Bearer Idempotency-Key: ``` Each response returns a generated `@test.sigid.dev` email and password once. Use the fixture accounts through the application's normal **Sign in** button so hosted login, consent, callback handling, token validation, and application authorization all run on the production-shaped path. Never use the fixture accounts to accept an operator handoff; fixtures cannot receive organization authority. For role-driven applications, give each fixture a named purpose, for example: | Persona | Application state to create | Developer check | |---|---|---| | Document owner | Draft document and signature request | Open the recorded document URL | | Signer | Pending signature task | Open the inbox and sign the draft | | Viewer | Read-only shared document | Confirm editing is denied | ### 4. Preserve A Reproducible Test Manifest Create `.dev/sigid-test-handoff.md` or an equivalent secret-free artifact and deliver it with the handoff. Include: ```markdown # SigID test handoff - Issuer: https://tenant.example - Client ID: ... - Application: ... - Fixture credentials: .dev/sandbox-fixture.env (sent separately) - Persona: document-owner – fixture user ID ... - Test URL: http://localhost:3000/documents/... - Expected state: draft with one pending signer - Reproduce: sign in, open the URL, invite the signer persona, verify read-only viewer denial ``` Do not put passwords, bearer tokens, client secrets, or the handoff token in the manifest. If the application cannot provide a durable deep link, record exact navigation and deterministic seed steps. This is the bridge between SIGID's identity handoff and application-owned sample data. ### 5. Transfer The Agent And Resources After integration and testing, issue an operator **handoff**: ```bash sigid-cli handoff \ --idp "$SIGID_IDP" \ --organization-id "$SIGID_ORGANIZATION_ID" \ --agent-id "$SIGID_AGENT_ID" \ --application-id "$SIGID_APPLICATION_ID" ``` Send the returned fragment-bearing link only to the intended developer. The link expires after seven days and is single-use. The developer signs in with their own human SigID account and accepts. Acceptance: - transfers `agent.owner_user_id` to that human; - grants organization co-ownership by default; and - grants the application-targeted `developer` role for every supplied `--application-id`. Use `sigid-cli invite` only when the human should gain resource access without owning the agent. Temporary human-to-agent AAL2 delegation is also separate; a handoff does not create it. ### 6. Preview, Activate, Save, And Retest Branding The accepting developer opens **Dashboard → Branding → Theme** and previews the prepared app name, logo, theme, and login-method configuration while the organization is still sandbox-tier. When ready for production, the human owner completes the separate AAL2 activation ceremony and selects a plan with the `branding` entitlement before saving. Activation intentionally retires the sandbox fixture accounts. Create or invite a normal production test user, repeat the hosted authorize/callback flow, and update the test manifest with the production-safe test path. Never carry a standing sandbox demo password into production. ## Handoff Checklist - [ ] The real hosted authorize/callback path passes with a fixture human. - [ ] Multiple application roles use separate fixture humans, not agent accounts. - [ ] Application-owned sample data has a deep link or deterministic seed recipe. - [ ] Fixture credentials remain in a private, gitignored file or secret channel. - [ ] The accepting human previewed app name, logo, theme, and login methods. - [ ] Saved branding was tested after activation and entitlement with a normal non-fixture user. - [ ] The handoff includes every application the developer must manage. - [ ] The developer accepted with their own human account and reproduced the test.