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:

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¶

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:

PATCH /api/v1/control-plane/tenants/{tenant_id}/config
Authorization: Bearer <organization-authorized token>
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:

POST /api/v1/sandbox/fixture-users
Authorization: Bearer <tenant token with users:manage>
Idempotency-Key: <new UUID>

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:

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:

# 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:

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.