Credentials

Everything Tenbi does on your behalf — running your AI agents (Claude or Codex), reading tickets, pushing branches, opening PRs, posting notifications — is done with credentials you provide. This chapter covers all of them: the Anthropic credential that powers the agents, the reusable service credentials your modules attach to, and how Tenbi stores, verifies, rotates, and deletes secrets.

It lives in two places, split by who manages it: the workspace key, payment policy, and the shared service credentials are on Workspace → Settings (owner/admin); your own personal AI credential is under Settings → Credentials (the gear in the top bar).

Two rules apply to every secret on this page:

• Encrypted, write-once. Secrets are encrypted at rest (AES-256-GCM) and never shown again after saving — the UI only ever displays the last few characters (•••• abcd) so you can tell which secret is loaded.
• Yours alone. Tenbi is multi-tenant: credentials belong to your account, are invisible to every other account, and can only be attached to your own modules. Runs bill your credential or they fail — they never borrow anyone else's.

The Anthropic credential (the workspace key)

Every run is a team of Claude agents working your ticket, and they run on your Anthropic credential — Tenbi never marks up or meters your usage. This credential is required: an account without one can't run anything. Runs fail immediately with an authentication error that links you back to this page (see Model key invalid for the triage steps).

It sits on Workspace → Settings, under Anthropic. There are two auth modes; the API key is the one to use.

API key — recommended

An API key from the Anthropic Console is the supported way to run Tenbi — as the UI puts it, it's the path Anthropic's terms support for third-party products.

1. In the Anthropic Console, create an API key (you may need to set up billing first).
2. Paste it into the Anthropic API key field and press Save.

What to expect on a metered key:

• Billing — runs bill per token, by Anthropic, to you, at their standard prices. A typical run costs a few dollars; every run's cost is visible in Analytics.
• Capacity — isolated. There's no shared usage window to exhaust, so run volume and your own personal Claude use never collide.
• Model access — the key must have access to whatever model your runs select; a key without access to the selected model fails the run with an auth error, same as a missing key.

Picking a default model

The model is the biggest cost/quality lever you have. It's set in Workspace → Settings → Models, as the Workspace base model — the change saves automatically, no Save button, and it sits beside the agent choice so the list always matches your provider. The list follows your workspace's agent provider: Claude workspaces start on Opus 4.8, the most capable tier for coding work (Sonnet 5 is the balanced alternative); Codex workspaces start on GPT-5.6 Sol, the Codex default (Terra and Luna are also available — see Choose your AI). Individual Lanes can override the model per-Lane, and a Lane override takes precedence (see Lanes).

Reasoning effort

The second lever is reasoning effort — how much the agent thinks before acting. It's set alongside the base model in Workspace → Settings → Models, with project defaults and a per-lane override on top. Workspaces start on High, the recommended balance; raise it (X-High, or Max on Claude) for Lanes that carry complex work, or lower it for simple, high-volume Lanes. Higher effort spends more output tokens — the run record shows each run's effort next to its cost.

In subscription (OAuth) mode, the model must be one your Claude plan includes.

Subscription (OAuth) authentication — at your own risk

Tenbi can also run against a Claude Pro/Max subscription via an OAuth token instead of an API key. The Use subscription (OAuth) mode for runs toggle sits directly under the agent picker: while it's off you see only the API-key field (the supported path); switching it on replaces the key field with the subscription setup — and you should understand exactly what you're accepting before enabling it.

This mode is not supported by Anthropic's terms. Anthropic's Consumer Terms prohibit using Claude subscription credentials in third-party services (§2, §3.7; clarified February 2026), and Anthropic enforces this with automated account suspensions. Using a subscription token with Tenbi can get your Anthropic account banned — mid-run, without warning. Tenbi cannot prevent or reverse this. The supported path is an Anthropic API key.

The one-time acknowledgment. With the toggle on, the token field stays disabled — and Save stays disabled — until you check the acknowledgment: I understand the risk. This isn't a cosmetic checkbox — the server enforces the same gate and rejects the save (HTTP 422) without it. Once acknowledged, the panel shows Risk acknowledged on the date instead, and you won't be asked again.

The usage-window caveat. A subscription is flat monthly cost, but runs share your subscription's rolling usage windows with everything else on that account. Heavy run volume — or running Tenbi alongside your own Claude use — can exhaust a window mid-run, and those runs fail as rate limited until the window resets.

Getting the token (one time, ~2 minutes, on any machine with the Claude Code CLI installed):

1. Run claude setup-token in a terminal.
2. It opens (or prints) a claude.ai authorization link — open it, sign in if asked, click Authorize.
3. The browser shows a code — paste it back into the terminal prompt.
4. The terminal prints a long-lived token starting with sk-ant-oat… — paste it into the Claude Code OAuth token field.

Which account gets billed? The token belongs to whichever account that terminal's Claude Code is signed into. If you have more than one (say, work and personal), run claude /status first to check — you're about to point every Tenbi run at that subscription.

To activate the mode: toggle on → acknowledge → paste the token → Save. OAuth tokens expire — when a working setup starts failing runs with auth errors, generate a fresh token with claude setup-token and re-paste it.

A note on cost figures in this mode: per-run dollar amounts shown in Tenbi are the API-equivalent value of the usage — an estimate of what the run would have cost on a metered key, not a bill. Spend totals in Analytics count metered runs only.

Mode selection — there is no fallback

Only the credential for the selected mode is ever used. You can keep both secrets stored and switch modes any time — switching is instant and reversible — but:

• Selecting OAuth mode with no token saved fails your runs with an authentication error even if an API key is on file, and vice versa.
• Tenbi never falls back across accounts: your runs bill your credential or they fail.

The OpenAI credential (Codex — Beta)

Shown when your AI agent is set to Codex (OpenAI). Codex runs bill your OpenAI Platform account.

1. Create an API key at platform.openai.com → API keys. Keys look like sk-proj-….
2. Fund the Platform wallet: platform.openai.com → Settings → Billing → Add to credit balance (a few dollars goes a long way; you can also add a card).
3. Paste the key into the OpenAI API key field and press Save.

The wallet trap — read this before buying credits. ChatGPT and the OpenAI Platform have separate wallets. A ChatGPT subscription or ChatGPT credits do not fund API keys — if your account holds ChatGPT credit but the Platform balance is zero, every Codex run fails on quota (insufficient_quota). Make sure the money is on platform.openai.com, in the same organization/project that owns your key (check the org switcher, top-left).

If a Codex run fails immediately at startup, see Codex authentication failed.

Service credentials

On Workspace → Settings (owner/admin), the Service credentials card holds the secrets for the services your tickets and repos live in — GitHub, Jira, Bitbucket, and so on. They're reusable on purpose: you enter a secret once, and any number of connections can point at the same credential. That's also what makes rotation painless — replace the token in one place and every connection using it picks up the change.

Who manages these. They're shared across the workspace — every member's connections and runs use them — so they live in the admin area (Workspace → Settings) and adding, editing, or deleting one is an owner/admin task. Members don't see the pool itself, but they can pick any of its credentials when building a connection.

To add one, press Add, pick a Type, give it a Name (e.g. GitHub — personal), fill in the fields, and press Create. For most types there's a Verify button right on the form — use it as you go; a credential verified at creation time is far easier than debugging a failed run later.

What each type needs

Type	Fields	Minimum access
GitHub PAT	Personal access token	Classic: repo scope · Fine-grained: Contents R/W, Pull requests R/W, Metadata R (+ Issues R/W for Ticketing)
Jira Cloud	Site URL, Account email, API token	Your Jira user's project access
Shortcut	API token	Your workspace access
Bitbucket Cloud	Account email, API token	Repositories R/W, Pull requests R/W
Azure DevOps PAT	Personal access token	Code: Read & write
Discord webhook	Webhook URL	—
Slack webhook	Webhook URL	—
Microsoft Teams webhook	Workflow webhook URL	—

GitHub PAT

Used by GitHub Ticketing and Version Control modules. One field: Personal access token (ghp_… or github_pat_…). Scopes are the single most common setup failure, so get them right up front:

• Classic PAT — the full repo scope. public_repo is not enough: private repos become invisible and read as 404s. The same repo scope also covers issues for Ticketing use.
• Fine-grained PAT — three things must all line up:
  • Resource owner is the account/org that owns the repo (a personal token can't see org repos unless the org allows it).
  • Repository access explicitly includes your target repos — the default allow-list silently excludes repos created after the token.
  • Permissions: Contents: Read and write, Pull requests: Read and write, Metadata: Read — plus Issues: Read and write if the same token backs a Ticketing module.

404 means scopes, not "missing". On GitHub, a private repo your token can't see returns 404, not 403 — "not found" almost always means the token's scopes or fine-grained allow-list, not that the repo doesn't exist. Full fix steps: VCS repo not found.

One quirk worth knowing: editing a fine-grained token's repository access on GitHub does not change the token value — you don't need to re-paste anything in Tenbi. Fix the access on GitHub and press Verify again.

Workflow files need an extra scope. If your tickets might change files under .github/workflows/ (GitHub Actions CI/CD definitions), the token needs GitHub's workflow permission or the push is rejected — even with full repo access. Classic PAT: also check the workflow scope. Fine-grained PAT: set Workflows: Read and write. Without it, a run does all its work but fails at the final push with "refusing to allow a Personal Access Token to create or update workflow … without workflow scope." Full fix: Workflow file push rejected.

Jira Cloud

Used by Jira Ticketing modules, if your tickets live in Jira. Three fields: Site URL (e.g. https://yoursite.atlassian.net), Account email, and API token (an Atlassian API token, created in your Atlassian account settings). The token inherits your user's project access — if you can't see a project in Jira, neither can Tenbi.

Shortcut

Used by Shortcut Ticketing modules. One field: API token. It inherits your workspace access; Verify confirms it by reporting the authenticated member.

Bitbucket Cloud

Used by Bitbucket Version Control modules. Two fields: Account email and API token, with Repositories: Read and write and Pull requests: Read and write permissions.

Azure DevOps PAT

Used by Azure Repos Version Control modules. One field: Personal access token, with Code: Read & write at minimum. Two things are different about Azure:

• The organization is not on the credential — it's set on the Version Control module, and repos are named project/repo (not owner/repo).
• There's no standalone Verify button for this type. An Azure PAT is org-scoped, so there's nothing to check it against on its own — it gets verified when you press Verify on a repo row (on the module or the Lane), which checks the PAT against a real repo.

Discord / Slack / Microsoft Teams webhooks

Used by Messaging modules, only if you want run notifications posted to a channel. One field each: Webhook URL. For Discord and Slack, paste the webhook URL from the channel settings. For Microsoft Teams, create a workflow from the channel's Workflows menu using the "Post to a channel when a webhook request is received" template and paste the HTTP URL it gives you — classic O365 connector URLs (retired by Microsoft, but still honored if you have one) also work. These can't be verified without actually sending a message, so the form tells you so instead of offering Verify — you'll know it works when the first notification arrives.

Verifying

Verify runs a live check against the provider — it's the difference between "the token is saved" and "the token works." Two behaviors worth knowing:

• You can re-verify a stored credential without re-pasting it. Open the credential with Edit, leave the masked secret untouched, and press Verify — the stored secret is checked as-is. Do this after changing anything on the provider side (scopes, repo access, SSO authorization).
• Failures tell you why. A failed verify shows the provider's rejection and links to the matching fix — scopes for access problems, and a distinct expiry hint when a previously-working credential stops verifying (expiring token types: fine-grained GitHub PATs, Azure PATs, Anthropic OAuth tokens).

Verifying a credential is separate from verifying a repo — repo rows on Lanes and Version Control modules have their own Verify, which checks that this credential can reach that specific repo (and its base branch, when one is set).

How secrets are stored — and what you'll see later

Encryption at rest. Every secret — the Anthropic key, OAuth token, PATs, API tokens, webhook URLs — is encrypted with AES-256-GCM before it's stored. Non-secret fields (a Jira site URL, an account email) stay readable in the list; the secret itself never leaves the server again in any form.

Never shown again. After saving, the UI renders a saved secret as a masked value with its last few characters (•••• abcd) — enough to tell which key is loaded, never the key itself. There is no "reveal" — if you need the value, get it from the provider that issued it.

Replacing a secret. A saved secret field shows the mask with a Replace button. Press it to type a new value; Cancel — keep current secret backs out. Leaving a masked field untouched on save always means "keep the existing secret" — you never need to re-enter a secret just to rename a credential or edit its other fields.

Rotation is a one-field edit. When a token expires or you rotate it at the provider: Edit the credential, Replace the secret field, paste the new value, Save, Verify. Every module pointing at that credential picks up the new value immediately — nothing else to touch. This is the payoff of reusable credentials: rotate once, not once per module.

Deleting. Delete on a credential row asks for confirmation and is permanent — "This cannot be undone."

In use? Delete is refused. A credential a connection still binds can't be deleted — Tenbi blocks it and names the connections still on it, so a delete can never silently break a module mid-flight. Re-point those connections to another credential (or remove them) first, then delete. And note there's no disable switch on a credential: if you want to pause work rather than tear it down, disable the Lane instead (the Enabled toggle on the Lane) and leave the credential alone.

If a run fails on credentials

The failure callout on the record names the cause and links to the fix. The credential-shaped ones:

Symptom	Where to look
Run fails in seconds with an auth error, or "Anthropic credential needed"	Model key invalid
Repo verify or clone fails with not found / 404	VCS repo not found
Verify fails with 401/403, or a long-working Lane suddenly fails auth	PAT scopes and the auth sections around it

Once the credential is fixed, press Rerun on the record — reruns re-fetch the ticket and start fresh.

Whose key pays?

Every workspace has a payment policy (Workspace → Settings, owner/admin):

• Everyone runs on the workspace key (default) — all runs use the workspace's key or subscription. Exactly the behavior Tenbi has always had.
• Personal keys preferred — each run first resolves whose run it is: the first run of a ticket bills the ticket's assignee (via identity mappings); a rerun bills whoever pressed Rerun. If that person has a personal credential, it pays; otherwise the workspace credential covers it.
• Personal keys required — same resolution, but with no fallback: a run with no resolvable person, or a person with no stored credential, fails with a message pointing at the fix. Use this when every teammate should pay their own way.

Two rules hold under every policy: indexer and generation runs always use the workspace credential (they're infrastructure, not anyone's ticket), and each run records which key paid — personal-key runs show a Personal key tag on the run detail.

Three governance controls sit beside the policy on Workspace → Settings:

• Require attribution mapping for ticket runs — on, a ticket run with no mapped assignee (and no sole member) fails at pickup with a message naming the fix, instead of running as Unattributed on the workspace key.
• Members may add personal keys — off, stored personal keys are kept but never used; every run bills the workspace key. It can't be off while the policy is Personal key required — the two settings contradict.
• Personal key agents — which agents members may add personal keys for. Claude only out of the box; enabling Codex (Beta) lets members store an OpenAI Platform key. Unticking an agent blocks new keys of that type — already-stored ones are kept (and removable), just never used. At least one agent always stays on; turning personal keys off entirely is the switch above.

A personal Claude key pays under the personal policies today. A personal Codex key is stored but not yet used for runs — it activates when per-run agent selection ships, with nothing to re-enter. Runs today always use the workspace's active agent.

Where to go next

With your Anthropic credential and service credentials saved and verified, the next step is a project — its ticketing destination and repos bind connections backed by these credentials. The full zero-to-first-PR walkthrough is in First Steps.