Accounts and permissions

Quick Share needs no account. Everything on your own domains (routes, shares on your domain, Snapshots, logins, edge protection) goes through a Cloudflare account you connect once. This page covers the ways to connect, what Teitunnel asks Cloudflare for and why, and what to do when a permission is missing.

Connect an accountCopy Anchor Link

Open Settings ▸ Accounts and choose Connect an Account. Before any account is connected, the Overview's Use My Own Domain… opens the same sheet.

There are three ways to connect:

Which one to useCopy Anchor Link

On a desktop, Sign in with Cloudflare is the quickest. Use an API token when you want to limit what Teitunnel can reach, on servers and in containers (Servers and containers), and in CI.

The consent screenCopy Anchor Link

Sign in with Cloudflare asks for everything Teitunnel can do in one consent, so you don't come back for each feature. Four scopes are required; without them Teitunnel can't put anything on your domains. offline_access keeps you signed in. The rest are optional: you can decline any of them on the consent screen, and Teitunnel keeps working without the features they belong to. When you later use one of those features, Teitunnel shows what's missing and how to add it, in place (see When a permission is missing).

offline_access is how Cloudflare hands out a refresh token. If it's refused, Teitunnel says Cloudflare didn't allow offline access and the sign-in doesn't complete.

Every permission, and what needs itCopy Anchor Link

API tokens use the dashboard's permission names. The link behind Open Cloudflare selects everything in the first part of this table; the last rows are added by hand if you use those features.

Only the first four are needed for routes. Everything else is optional: without it, the feature says what's missing when you open it, and the rest keeps working. With an API token, Cloudflare Tunnel · Edit also covers private networks; a sign-in asks for them separately (teams-networks.write, and teams.read for the Doctor's WARP checks). The same list, with the token link's keys, is in Permissions and scopes.

See what an account can doCopy Anchor Link

In Settings ▸ Accounts, open Permissions under an account. Teitunnel checks with Cloudflare, without changing anything, and lists:

Each row is Allowed (a check mark), Not allowed (a cross), Unknown (a dash: Cloudflare couldn't be asked just now, for example offline) or Needs Cloudflare Zero Trust, which isn't set up yet. Domains' own permissions are also shown in Domains, per domain.

When a permission is missingCopy Anchor Link

Teitunnel doesn't stop at an error. Wherever a feature needs something the account's credential lacks (a route's login, the Doctor, Snapshots, protection, this Permissions list), it shows a card, The token needs one more permission, listing each missing permission by its dashboard name and why it's needed.

For an API token, the token keeps its value, so nothing is pasted:

Teitunnel checks again when its window becomes active (or choose Check Again) and carries on where you were; a change you were reviewing is planned again. If something is still missing, the card says so.

Or choose Use a New Token Instead: Create Token opens the dashboard with every permission selected, and the token you paste replaces the account's credential.

For an account connected with Sign in with Cloudflare or a cloudflared login, the permissions of that login can't be edited. The card offers to connect the account with an API token that has them (Create Token, then paste it); it replaces the current credential, and everything you set up stays.

Set up Cloudflare Zero TrustCopy Anchor Link

Logins and service tokens use Cloudflare Zero Trust (Access). An account that has never used Zero Trust has the permissions but nothing to use them on yet, so instead of a permission card Teitunnel shows Set up Cloudflare Zero Trust:

1. Open Zero Trust and choose a team name.
2. Pick the Free plan when asked (free for up to 50 users), then come back.

Only the dashboard can do this step. Teitunnel checks again when you come back (or choose Try Again) and carries on. Adding a domain to Cloudflare works the same way: Add a Domain to Cloudflare opens the dashboard's page for it.

Several accountsCopy Anchor Link

One sign-in or token can reach several Cloudflare accounts; each one it reaches is connected, and you can connect more with Connect an Account. With more than one connected:

• Routes, Domains, Tunnels, Analytics and Activity have an Account menu in the toolbar. The account you pick is remembered; if it's disconnected, the first account is shown.
• Quick Share's Address menu lists your domains, so a share can go on any of them.
• On the command line, commands that work on one account take --account with the account's name or id. It's needed only when several are connected.

Disconnect an accountCopy Anchor Link

In Settings ▸ Accounts, choose Disconnect next to the account and confirm. Teitunnel:

• stops this computer's connectors for the account and ends temporary shares on its domains (their routes and records are removed while the credential still works);
• revokes the sign-in with Cloudflare, for accounts connected with Sign in with Cloudflare;
• deletes the account's credentials from your keychain;
• deletes what it remembered about the account on this computer (activity, ownership notes, Snapshots list, schedules and the like).

Its tunnels, routes and DNS records stay in Cloudflare, offline until a connector runs them again. To remove them too, remove the routes first. An API token isn't deleted from Cloudflare: delete it in the dashboard's API Tokens if you no longer need it.

Where credentials are keptCopy Anchor Link

Credentials are kept only in your system's credential store: the keychain on macOS, Windows Credential Manager on Windows, and the Secret Service (GNOME Keyring or KWallet, installed and unlocked) on Linux. They're stored under the service com.teispace.teitunnel:

An API token that reaches several accounts is stored once per account, so each account can be disconnected on its own. A Cloudflare sign-in is stored once for all the accounts it reaches (older versions kept an item per account, under its id), and it's revoked when the last of them is disconnected. The database only holds each account's id, name and how it was connected. Credentials are only ever sent to Cloudflare, and never reach the app's window, logs or AI agents. See Security.

Cloudflare gives a sign-in a new refresh token every time it's used, and ends the sign-in if an old one is used again. So the accounts a sign-in reaches share one refresh token, and the app, the teitunnel command and the MCP server for AI agents share one access token through the keychain; only one of them refreshes it at a time.

If Cloudflare ends a sign-in anyway (you revoked it in the dashboard, or it wasn't used for a long time), its accounts show Signed out in Settings → Accounts with Sign In Again. Teitunnel stops asking Cloudflare until you do.

From the terminalCopy Anchor Link

The teitunnel command uses the accounts connected in the app, including sign-ins.

teitunnel accounts            # connected accounts: name and id
teitunnel accounts --json     # [{"id": …, "name": …}]
teitunnel setup               # connect an account with an API token (asks for it)
teitunnel routes --account Teispace

teitunnel setup asks for an API token (with Cloudflare Tunnel · Edit, DNS · Edit and Zone · Read at least) and stores it in the keychain like the app does. Signing in with Cloudflare is only in the app, since it needs a browser.

On a server or in a container without a keychain, don't store a token: set CLOUDFLARE_API_TOKEN (or TEITUNNEL_API_TOKEN) for each command, or CLOUDFLARE_API_TOKEN_FILE naming a file that holds it, as Docker secrets do. It's used for that command only and never written to disk. With it set, teitunnel setup only checks that it works. See Servers and containers.

TroubleshootingCopy Anchor Link

• Cloudflare didn't accept this token. Check that you copied all of it and that it hasn't expired or been deleted in the dashboard.
• This token can't access any Cloudflare account or domain. It was created without resources. Create it from Open Cloudflare so all accounts and domains are selected.
• Couldn't start sign-in: ports … are all in use. The sign-in listens on this computer on port 53682, 53683 or 53684. Close other sign-in windows and try again.
• Sign-in timed out. You have 5 minutes to finish in the browser. Try again.
• Invalid access token (9109). See Troubleshooting.
• The keychain couldn't be used. Unlock it and try again. On Linux, install and unlock a Secret Service provider such as GNOME Keyring or KWallet.

RelatedCopy Anchor Link