Zozo Docs

Auth & Consent ​

Signing in and running agent work involve four independent authentication relationships:

  1. Your Control Plane browser session at app.zozohq.com manages your hosted account and billing.
  2. Your Stack browser session at <your-stack>.zozostacks.dev opens your private Dashboard.
  3. A Credential lets a vendor Runtime run Claude or Codex on your behalf.
  4. The Dispatcher uses a separate GitHub credential to read repositories and Issues, push branches, and open Pull Requests.

Each relationship can be validated, revoked, or repaired without changing the others.

Sign In to the Control Plane ​

Open app.zozohq.com to sign up or return through GitHub OAuth. After authentication, the Control Plane creates an opaque, revocable, server-side browser session. Your browser holds that session rather than a copy of your GitHub session or a tenant API key.

The signup page reads GET /v1/signup/config before presenting account creation. Its { inviteGate, signupsPaced } response reflects the live signup controls. When the invite gate is open, you can continue directly with GitHub; a valid invite code remains usable and receives priority over the daily signup allowance. When the daily allowance is full, the page offers the Interest List and new public signups resume after the next UTC midnight.

Revoking the session takes effect on its next use. The session authorizes your account and billing actions on the Control Plane only.

Continue to Your Stack ​

After you sign in to the Control Plane and complete account setup, it provisions your Stack. When the page shows Your Dashboard is ready, select Open your Dashboard. The Control Plane sends your browser to <your-stack>.zozostacks.dev with a short-lived, single-use code. Your Stack redeems the code and creates its own local browser session. See Quickstart for the complete sign-in and setup path.

The two sessions remain independent. Signing out of one surface doesn't silently grant or revoke access to the other. See Two Surfaces for the boundary between them.

A Credential is the named authentication artifact that a Provider supplies to its Runtime for a Run. It can be a Claude OAuth token, a Codex auth file, or a vendor API key. Your Stack stores each value in its secured credential store and keeps it outside every Thread's Event journal.

Each Credential has its own name. You can connect more than one to the same Provider, such as your personal subscription and a client's API key. A Project chooses one named Credential for each Provider, and a Thread keeps the selected Credential for its lifetime.

Choose the kind based on who pays for the work:

  • Personal subscription Credential: Recommended for a Solo tenant running Zozo against their own repositories and spending their own money. Your hosted Plan doesn't add a subscription-inference charge, while an API key would add metered vendor charges.
  • Vendor API key: Recommended for a Billed tenant running unattended work for a client they invoice. The vendor explicitly supports this mode, and its metered inference cost can be billed to the client.

Both kinds are available to every tenant. These recommendations are cost and operating guidance, not plan restrictions.

A personal subscription Credential lets Zozo use your existing paid subscription for automated work while you're away. Explicit consent ensures your Stack can use it for unattended work only after you authorize that use. Consent is recorded server-side for that Credential's name. A vendor API key doesn't require this consent step.

Consent belongs to the exact Credential name because each name can identify a different personal subscription. Consent for one name doesn't cover another name, even when both use the same Provider. Rotating a Credential under its existing name preserves its recorded consent. Deleting it deletes the consent, so adding that name again requires a new confirmation.

How Credential Validation Works ​

When you save a Credential, your Stack exercises the selected Runtime with a real, throwaway check before storing the value, so a rejected value is never saved. This applies to every Provider, including OpenCode. Each later Run reaffirms or updates that Credential's health status through ordinary use.

Self-refreshing Credentials, such as a Codex auth file, can refresh their authentication material on your Stack. Zozo validates a refresh before promoting it to the secured credential store. A definitive authentication rejection marks that named Credential invalid; a temporary network or refresh failure leaves its previous health unchanged.

A Credential saved before this check existed needs a re-save

A Credential provisioned before your Stack started running this save-time check has no recorded health verdict. Credentials shows it with a not validated badge, distinct from authenticated and invalid, and it's refused for Intake and Dispatch until you save it again with the same value. See Connect OpenCode with OpenRouter for the OpenCode case.

An OpenCode Credential has one more outcome: when OpenRouter reports the key has run out of credit, Zozo still marks it authenticated (the key itself works) and pauses that Credential until you add credit, since there is no way to know in advance when your balance allows a Run to start again.

Credential health and Runtime availability answer different questions. A working Runtime can have an invalid Credential, and one invalid Credential doesn't affect another on the same Provider. See Understanding Credentials for routing and health details.

Connect GitHub for the Dispatcher ​

Watching a Project also requires a GitHub credential. The Dispatcher uses it to read repositories and Issues, create and push branches, open Pull Requests, and update labels. This credential authorizes repository operations; it doesn't choose which vendor subscription a Run uses.

Zozo supports both GitHub personal access token types:

  • Fine-grained token: Use one for repositories you own. You can limit it to the specific repositories Zozo watches and grant only Contents read and write, Issues read and write, Pull requests read and write, and Metadata read-only permissions.
  • Classic token: Use one when Zozo must watch a private repository owned by someone else where you have collaborator access. Fine-grained tokens omit those repositories from the Projects picker, while classic tokens honor collaborator access. Grant the repo and read:org scopes, and use the narrowest repository access your work allows.

The GitHub credential stays on your Stack and has no subscription-consent step. Setup lets you choose either token type and verifies it against GitHub when you save it.

Vendor Terms and Your Subscription Credential ​

When you connect a Claude or Codex subscription Credential, that subscription remains governed by your agreement with Anthropic or OpenAI. Zozo isn't a party to that agreement and can't promise that a vendor permits every way you use its subscription with Zozo. You are responsible for reviewing and following the terms that apply to your account.

Zozo may disable support for a vendor's subscription Credentials if the vendor asks it to or if continued support would conflict with the vendor's terms. If that happens, you can continue using that Provider with an API-key Credential, which is always available.

Your subscription Credential stays in the secured credential store on your Stack. The vendor receives it when its own Runtime authenticates your work. Zozo's Control Plane doesn't receive the credential value.

Docs for Zozo: a coding-agent harness.

Copyright © Zozo