Credentials

Cate needs credentials to interact with your issue tracker. GitHub supports OAuth or a personal access token (PAT), Jira uses email plus an API token, and Linear uses OAuth. Credentials are stored securely on your machine and never written to the repository.

GitHub credentials

GitHub supports two authentication methods: OAuth (recommended) and a personal access token.

OAuth

Open Settings → Accounts in Cate and click Sign in with GitHub. Cate completes the OAuth handshake and stores the resulting access token, refresh token, and expiry. Tokens are refreshed automatically — see Token refresh.

Personal access token

If you prefer a PAT — for example, when OAuth is not available for your organization — generate one with the scopes below.

Required token scopes

• repo — read and write access to repositories (code, issues, PRs)
• project — read and write access to GitHub Projects boards
• read:org — required if you are using organization repositories

Create a token

1. Go to GitHub -> Settings -> Developer Settings -> Personal access tokens
2. Click Generate new token (classic)
3. Select the required scopes above
4. Copy the token immediately — GitHub shows it only once

Configure in Cate

Open Settings → Accounts and enter your GitHub credentials (OAuth or PAT). Cate validates them against the GitHub API before saving.

You can configure global credentials (used for all repositories) or per-repository credentials (useful when you have repositories under different accounts or organizations with different access levels). See Project-specific credentials.

Jira credentials

Jira uses email address and API token authentication rather than a personal access token.

Create a Jira API token

1. Go to id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a descriptive name (for example, “Cate”)
4. Copy the token immediately

Configure in Cate

Open Settings from the Cate dashboard, select Issue Tracker, choose Jira, and enter:

• Site URL — your Jira site (for example, mycompany.atlassian.net)
• Email — the email address for your Atlassian account
• API token — the token you just created

Cate validates the credentials by connecting to your Jira instance before saving.

Linear credentials

Linear authenticates via OAuth.

Sign in with Linear

Open Settings → Accounts in Cate and click Sign in with Linear. Cate completes the OAuth handshake and stores the resulting access token, refresh token, and expiry. Tokens are refreshed automatically — see Token refresh.

GitHub is also required

Linear references pull requests, so you also need GitHub credentials configured. Add them under Settings → Accounts before connecting a Linear team. See Connect to Linear for the full flow.

Rotating credentials

To rotate a credential:

• PAT or API token (GitHub, Jira) — generate a new token, open Settings → Accounts, enter the new token, and save.
• OAuth (GitHub, Linear) — click Sign in with GitHub or Sign in with Linear again to re-authenticate.

Cate uses the new credentials immediately on the next API call — no restart required.

Credential storage

All credentials are persisted in a single encrypted file:

<data-dir>/credentials.bin

The data directory defaults to:

Platform	Default path
macOS	~/Library/Application Support/Cate/
Windows	%APPDATA%\Cate\
Linux	~/.config/Cate/

You can override this with the --data-dir CLI flag.

What gets stored

Provider	Secrets stored	Auth method
GitHub	Access token, refresh token, expiry	OAuth or PAT
Jira	Email, API token, refresh token, cloud ID, expiry	OAuth or PAT
Linear	Access token, refresh token, expiry	OAuth or PAT

OAuth client IDs and client secrets are not stored in the credentials file — they are bundled into the application at build time.

Encryption

Cate uses Electron’s safeStorage API, which delegates encryption to your operating system’s native credential manager. This is the same mechanism that browsers, Git, and other desktop apps use to protect sensitive data.

OS-native encryption

Platform	Backend
macOS	Keychain Services — the encryption key lives in your login keychain
Windows	DPAPI (Data Protection API) — the key is bound to your Windows user profile
Linux	libsecret — uses GNOME Keyring, KWallet, or a compatible secrets service

On macOS, this triggers a one-time keychain prompt the first time Cate encrypts or decrypts a credential. After you grant access, subsequent reads and writes happen silently. On Windows and Linux, access is typically granted automatically for the logged-in user.

AES-256-GCM fallback

If native encryption is unavailable (for example, a Linux server without a desktop keyring), Cate falls back to software encryption:

Property	Detail
Algorithm	AES-256-GCM (authenticated encryption)
Key derivation	SHA-256 hash of machine hostname and OS username
IV	12 random bytes, generated fresh for each encryption operation
Tamper protection	16-byte GCM authentication tag prevents undetected modification
Portability	Device-specific — the key is derived from machine identity, so the credentials file cannot be copied to another machine

The fallback activates automatically. No configuration is required.

Read and write flow

Saving a credential:

Credential → serialize → encode as base64 → encrypt → write to credentials.bin

Loading a credential:

Read credentials.bin → decrypt → decode base64 → deserialize → credential

If decryption fails — for example, after a machine migration or a corrupted file — Cate deletes the credentials file and prompts you to re-authenticate. No partial or garbled data is returned.

Token refresh

OAuth providers issue time-limited access tokens alongside a refresh token. When an access token expires, Cate automatically exchanges the refresh token for a new one and persists the updated credential. This happens transparently — you do not need to re-authenticate unless the refresh token itself is revoked.

Security summary

• Credentials are encrypted at rest using OS-native encryption when available
• The credentials file never leaves your machine — it is not synced, committed, or transmitted to Blue Ghost
• OAuth client secrets are not stored in the credentials file
• The fallback encryption key is device-specific and cannot be used on another machine
• Failed decryption results in deletion, not exposure — you re-authenticate from scratch

Revoking access

To remove all stored credentials:

1. Open Settings → Accounts in Cate and disconnect each provider, or
2. Delete the credentials.bin file directly from the data directory listed above

Cate will prompt you to re-authenticate the next time it needs to access a provider.

Troubleshooting

If Cate reports a credential error, check:

• The token has not expired and has the required scopes
• The Jira site URL is correct (no trailing slash, no https:// prefix — just mycompany.atlassian.net)
• The Jira email matches the account that owns the API token
• For OAuth (GitHub, Linear), re-authenticate by clicking Sign in with GitHub or Sign in with Linear in Settings → Accounts