How authentication works

Teamwork Graph CLI (TWG CLI) authenticates you with Atlassian and uses your existing permissions when it accesses data. Your credentials are stored locally and reused across commands.

Personal sign-in uses OAuth 2.1. Bitbucket commands require a separate token, and admin commands use an organization-scoped API key.

OAuth 2.1

When you run twg login, TWG CLI offers to open a browser where you sign in to Atlassian and grant access. You can also open the printed verification URL yourself. Your credentials are saved locally and refreshed automatically, so you usually won't need to sign in again.

To set up OAuth 2.1, see Configure OAuth 2.1.

Admin authentication

Site and organization admin authentication use an Atlassian Admin API key limited to your organization. The key is stored separately from your personal credentials.

To authenticate as an admin, run:

1
2
twg admin auth login --email <your-email> --org <your-org-id>

For non-interactive calls, set TWG_ADMIN_TOKEN to your Admin API key. Admin commands use this key in memory instead of saved credentials. Pass --org <id-or-name> for organization-scoped commands; the injected key does not inherit the saved login's organization.

The persistent admin login is stored in plaintext admin-auth.conf under the TWG config directory. It is independent of personal login profiles and encrypted storage. twg admin auth status reports the saved login and its path.

Bitbucket

Attach a Bitbucket token to your login profile with twg setup bitbucket.

Login profiles

Login profiles are available in TWG CLI v1.3.6 and later. They let you keep separate logins for different organizations without signing out each time you switch.

• Each profile has its own login, organization, default site, and optional Bitbucket credentials.
• TWG allows one profile per organization. Signing in again updates that profile's credentials.
• Choosing a profile for one command does not change your saved default.

How TWG chooses a profile

TWG checks these options in order and uses the first that applies:

1. Command-line profile: --profile <name> (or -p <name>) selects a login for that command. Use --profile default to select the saved default, whatever its name.
2. Shell profile: TWG_PROFILE selects a login for commands in your shell.
3. Site selection: --site <site> selects a profile for that site's organization.
4. Saved default: Without a profile or site selector, TWG uses the saved default profile and its default site.

When you use --profile or TWG_PROFILE, TWG keeps that login even if you also supply --site. An organization mismatch or permission error returns an error; TWG does not try another profile.

Inspect and refresh profiles

• List your logins: twg auth profile list.
• Export the selected session: twg env --export.
• Run a binary with the selected session: twg env --profile work --exec -- python script.py. TWG refreshes saved OAuth credentials when due before launch and passes effective access credentials, site, profile, and endpoint in the child environment. The binary must read the TWG variables to authenticate requests. Credentials remain a snapshot during the run; long-running tools can outlive their access token. Runtime credential overrides remain caller-managed. Refresh failure prevents launch. Arguments after -- pass through literally; terminal streams and child exit codes are preserved. On POSIX, executable names or paths containing = are rejected with status 126; arguments may contain =.
• Refresh all profiles: twg auth refresh. The upkeep helper also maintains all profiles.
• Refresh one profile: twg auth refresh --profile <name>.

For creating profiles, naming rules, defaults, and removal, see Manage login profiles.

Permissions are always respected

TWG CLI can read or modify only the Atlassian data your account already has access to. Authentication does not grant additional permissions.

Token lifecycle

OAuth access tokens expire after 8 hours. TWG CLI refreshes them as needed, but an agent sandbox may block refresh. twg setup enables the upkeep helper to refresh credentials outside the sandbox. You can also enable it with twg upkeep enable. After 30 days without use, the refresh token expires and TWG CLI asks you to sign in again.

You can re-authenticate at any time by running:

1
2
twg login --force

To sign out and remove the active login and its saved credentials, run:

1
2
twg logout

TWG tries to revoke the profile's OAuth token. To remove a particular login, use twg logout --profile <name>. Removing the default selects the oldest usable remaining profile, excluding profiles pending deletion.

Organization admins can revoke active TWG CLI sessions after changing OAuth permissions in Atlassian Administration. You must sign in again before TWG CLI can use the updated permissions.

Experimental encrypted credential storage

TWG CLI can store encrypted credentials in auth-storage/auth.db instead of auth-profiles.json. This experimental option keeps the root key separate: in the OS vault by default on macOS and Windows, or supplied through TWG_AUTH_STORAGE_KEY on any supported OS. An environment-key database requires its original key for every command.

Existing auth.conf logins keep working; profile-writing operations import them automatically. TWG can verify missing organization details when routing to another site without requiring a new login. To opt into encrypted storage, use twg auth storage migrate; it moves all profiles, credentials, and defaults between the two stores. Both use the same selection rules. See Enable experimental encrypted credential storage.

twg doctor --basic shows which credential store and root-key source are in use.

Next steps

• Configure OAuth 2.1
• Troubleshoot TWG CLI
• To see what's changed in recent versions, view the changelog.