Configure OAuth 2.1 for Teamwork Graph CLI

OAuth 2.1 is the supported interactive sign-in method for Atlassian data in Teamwork Graph CLI. Bitbucket commands use a separate token. TWG CLI stores credentials in its config directory and can optionally use experimental encrypted credential storage.

More about how Teamwork Graph CLI auth works

Configure OAuth 2.1

1. In your terminal, run:

   twg login

   TWG CLI displays a verification URL and a short user code, then opens your browser automatically. If the browser doesn't open, copy the URL and open it manually.

2. In your browser:

   • Select your Atlassian organization if you have more than one. If you have access to only one site, it's selected automatically.

   • Select the site you want to authorize (for example, mycompany.atlassian.net). If you have access to only one site, it's selected automatically.

   • Review the permissions the CLI is requesting, then select Accept.

3. Return to your terminal. TWG CLI confirms when your credentials have been saved. The storage location depends on whether you use the default file store or the experimental encrypted store.

Enable experimental encrypted credential storage

Encrypted storage keeps credentials in auth-storage/auth.db. The database is encrypted with a root key stored separately:

This option is not enabled automatically. Existing users continue to use auth.conf until they migrate.

macOS

Migrate existing credentials:

For a new or replacement login directly into encrypted storage:

Windows PowerShell

Migrate existing credentials:

For a new or replacement login:

Windows Command Prompt

Migrate existing credentials:

For a new or replacement login:

Linux

Linux requires the same unpadded base64url-encoded 32-byte root key to be available to each process that uses the encrypted store. Set TWG_AUTH_STORAGE_KEY in your environment before you run these commands, rather than typing the key on the command line.

For a new or replacement login:

Verify encrypted storage

To check which credential store is active, run:

When encrypted storage is active, the auth source shown is auth.db. The root key isn’t stored in the database. It’s held separately, in the operating-system credential vault on macOS and Windows, or in TWG_AUTH_STORAGE_KEY on Linux.

Coding agent access

• Ordinary reads require access to the active config directory, auth.db, and the relevant OS vault or Linux environment variable.

• Refresh, login, migration, and database recovery can require write access to the config directory.

• Keep the root key and OAuth tokens out of prompts, chat, and command arguments.

• Use twg upkeep enable outside the agent sandbox where appropriate so OAuth can refresh without handing credential rotation to the sandboxed agent.

Verify your authentication

To confirm authentication is working, run:

This checks your credentials and confirms your auth method, token status, and connected site.

Re-authenticate

To update your credentials at any time:

To force a full re-entry of all credentials:

Refresh OAuth credentials

TWG CLI normally refreshes OAuth credentials after 75% of the access-token lifetime has elapsed. To run that same non-interactive check explicitly:

The command returns successfully without rotating when the credentials are still fresh. Use --force only for manual repair or validation:

Before contacting the OAuth token endpoint, TWG CLI verifies that it can atomically update the active credential backend. This prevents a sandboxed coding agent from spending a one-time refresh token and then losing the rotated replacement.

If the config directory isn't writable, TWG CLI sends no refresh request and asks you to run twg auth refresh in a normal terminal. It also detects common coding agents and prints the relevant configuration.

Keep OAuth working inside coding agents

Coding agents often run commands in sandboxes that can't reliably update credentials outside the workspace. TWG CLI handles this by installing a small per-user upkeep helper during setup. The helper runs outside the agent sandbox, keeps OAuth credentials fresh, and sends update notifications when a new CLI version is available.

Keep upkeep enabled so agents can continue using TWG CLI without spending a one-time refresh token from inside a sandbox.

OAuth upkeep background helper

twg setup enables upkeep automatically. To repair or re-enable it manually:

The scheduler runs every 12 minutes. It refreshes OAuth only when the normal refresh threshold is within 15 minutes and checks for CLI updates at most daily with jitter.

When an update is available, it sends an initial native notification, up to three daily reminders, then up to three weekly reminders until you update. Each notification tells you to run twg update; upkeep never downloads or installs updates automatically.

Use these commands to inspect, run, or remove it:

TWG CLI uses a macOS LaunchAgent, Linux system user timer, or Windows Scheduled Task. The schedule invokes the stable TWG launcher so normal updates can replace the runtime safely. OAuth refresh still uses the same persistence preflight, cross-process lock, and atomic credential save as foreground commands.

On Linux, scheduling requires a system user instance and an active user D-Bus session. If setup can't install the schedule, it completes with repair guidance. Retrying twg upkeep enable reports the underlying systemctl --user error and leaves upkeep disabled.

The scheduler stores only non-secret maintenance state in upkeep.json under the active TWG config directory. twg logout leaves the schedule enabled but silently skips auth work until OAuth is configured again. twg uninstall disables the schedule, revokes stored credentials, and removes the CLI and all local TWG configs.

If you disable the background item, TWG CLI still works, but OAuth refresh and update notifications may not run in the background. Run twg auth refresh or twg update manually if needed.

If a command says the TWG config directory isn't writable, run twg auth refresh or twg login in a normal terminal outside the coding agent.

Bitbucket authentication

Bitbucket commands require a separate token. twg login does not configure it. Run twg setup bitbucket, or twg setup bitbucket --force to replace an existing token. For CI/CD, use the TWG_BBC_TOKEN environment variable.

Share feedback or report a bug