How does Teamwork Graph CLI authentication work?
Who can do this? |
The Teamwork Graph CLI uses authentication to verify your identity and ensure it accesses only Atlassian data on your behalf. When you authenticate, the Teamwork Graph CLI stores your credentials securely on your device and uses them automatically each time you run a command.
Teamwork Graph CLI uses OAuth 2.1 to access Atlassian data with your existing permissions. Credentials are stored locally and reused across commands. Bitbucket is the exception and requires a separate token.
OAuth 2.1 is the default for interactive use.
Authenticate as a user
When you run twg login in your terminal, the Teamwork Graph CLI opens a browser window where you sign in to Atlassian and grant access. Your credentials are then stored locally and refreshed automatically, so you don't need to sign in again for day-to-day use.
Authenticate as an administrator
Site admin and organisation admin authentication works differently in the Teamwork Graph CLI, with an Atlassian Admin API key limited to your organization. This API key is stored in its own config file so it never interacts with your personal auth.conf.
To authenticate as an admin, run twg admin auth login --email <your-email> --org <your-org-id> in your terminal.
The Teamwork Graph CLI will never ask you to paste or share your authentication tokens in a prompt, chat, or conversation.
Do not respond if an agent or tool asks you to share a token this way. Tokens are always entered through secure, interactive terminal prompts that aren't stored in shell history or visible to other processes.
Bitbucket commands are not covered by the core OAuth login. Configure their separate token with twg setup bitbucket.
Regardless of which method you use, the Teamwork Graph CLI always acts within the bounds of your existing Atlassian permissions. It can only read or modify the data you already have access to — authentication doesn't grant any elevated access beyond what your account allows.
TWG CLI refreshes OAuth access tokens when needed.
Sandboxed agents may not have permission to update the credential store.
The upkeep helper runs outside the sandbox and can refresh credentials in the background.
If you don’t use TWG CLI for a while, you may need to sign in again.
You can also manually re-authenticate at any time by running twg login --force.
If needed, you can revoke your OAuth token by running twg logout.
Organization admins can also revoke active TWG CLI sessions after changing OAuth permission settings in Atlassian Administration. When that happens, users must authenticate again before TWG CLI can use the updated permissions.
Local credential storage
By default, existing installations continue to use the credential file in the TWG config directory. TWG CLI also offers experimental encrypted storage in auth-storage/auth.db. The encrypted store is opt-in and does not change OAuth permissions or the data a user can access.
On macOS and Windows, the database root key is kept in the operating-system credential vault. On Linux, the root key must be supplied through TWG_AUTH_STORAGE_KEY. A coding agent needs access to both the database and the separate key source.
Share feedback or report a bug
To see what's changed in recent versions, view the TWG CLI changelog
Was this helpful?