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.

TWG CLI uses OAuth 2.1 as its only supported authentication method. The one exception is Bitbucket, which isn't covered by OAuth yet and requires a separate Bitbucket token.

OAuth 2.1

When you run twg login, TWG CLI opens a browser where you sign in to Atlassian and grant access. 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>

Bitbucket

Bitbucket is the only exception to OAuth support. Its commands require a separate Bitbucket token, set up independently with twg setup bitbucket.

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 credentials while commands run, but an agent sandbox may block refresh. During installation, twg setup enables the upkeep helper, which runs outside agent sandboxes and refreshes credentials in the background. You can also enable it later 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 revoke your OAuth token, run:

1
2
twg logout

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 now has an experimental option to store encrypted credentials in its vault at auth-storage/auth.db, instead of auth.conf. Its root key is stored separately: in the OS vault on macOS and Windows, or in the TWG_AUTH_STORAGE_KEY environment variable on Linux. This helps protect credentials from software that can inspect local files but cannot access the root key.

This option is not enabled automatically. Existing credentials continue to use auth.conf until you migrate them. New users can save their first login directly to encrypted storage. See Enable experimental encrypted credential storage.

After setup, twg doctor --basic shows which storage method is in use. The auth.db path identifies the encrypted database; the root key is stored separately.

Next steps

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