API Keys and Tokens
Use the credential type intended for the workflow. A provider token, Codity API key and CLI login credential serve different purposes.
Authentication Overview
| Workflow | Credential / entry point |
|---|---|
| Dashboard provider sign-in | OAuth, or the separate self-hosted GitLab sign-in |
| GitHub repository integration | Installed GitHub App and repository selection |
| GitLab.com repository operations | PAT entered on GitLab Repositories → Configure token / Update token → Token → Save token |
| Self-hosted GitLab | Instance OAuth application or token sign-in; see the separate guide |
| Azure DevOps | Shared organization PAT on the Organization-wide access token screen (/azure/pat) |
| Bitbucket Cloud | OAuth connection for the selected workspace |
| Public Codity API | Key managed in API Keys; see API overview |
| CLI | codity login or codity login --email; see CLI authentication |
Generating Tokens
Follow the provider guide for the required credential and current controls:
- GitHub: installation access, not a manually pasted PAT.
- GitLab.com: the current token form lists
apiandread_user; project membership and webhook rights also matter. - Self-hosted GitLab: instance-specific SSO or token connection.
- Azure DevOps: the current organization PAT form lists Code, Build, Work Items and Member Entitlement Management scopes.
- Bitbucket: the deployment's OAuth consumer defines its permissions.
Do not use the scopes from one provider or product for another. An Argo CD bearer token in a Codity One GitOps connector does not connect a GitLab repository for reviews.
Where Tokens Are Used
Provider credentials support the operations their owner and scopes allow, such as reading repository content, posting feedback or configuring notifications. Features that write code need applicable write access too. Dashboard sign-in does not prove every integration credential is valid.
Safe Storage Practices
Treat tokens, keys, invite links and session credentials as private. Paste a provider token only into its designated form. Do not paste it into Help, commit it or include it in a screenshot. Repository names, organization names and review contents can also be private; share only what you are authorized to share.
Token Rotation
Create a replacement with the required access, save it in the appropriate integration control and verify repository access plus an eligible test review. Then revoke credentials that are no longer needed. For a shared Azure PAT, replacement requires the configuring account or an authorized account admin.
OAuth sign-in credentials and manually entered PATs have separate lifecycles. Signing in again does not necessarily replace the stored repository PAT.
Replace a Provider PAT
For a planned rotation of a GitLab.com or Azure DevOps PAT:
Identify the account and provider using the credential. For a shared PAT, coordinate with its configuring user or account administrator.
Create a replacement through the provider using the access described in its setup guide. Check both token scopes and the token owner's project/organization rights.
Select the intended account in Codity and save the replacement in the correct control:
Provider Replacement control GitLab.com GitLab Repositories → Update token → Token → Save token Azure DevOps Organization-wide access token ( /azure/pat) → Token → Save tokenSelf-hosted GitLab Follow the instance's sign-in and connection guide; its connection is separate from GitLab.com. Check the save/validation result. Confirm the intended repositories remain accessible and run an eligible test review.
After verifying the replacement, revoke the old PAT in its provider if no other integration still needs it.
A successful token validation does not establish webhook or write access on every project. If one repository still fails, check that project's permissions and provider response before generating another token.
This planned sequence is for routine rotation. If a credential is exposed, revoke it promptly through its issuer, replace it and check affected integrations; do not leave an exposed credential active merely to complete a test review.
Rotate a Public Codity API Key
- Open API Keys for the intended account and create a replacement key. See API authentication for management access requirements.
- Copy the one-time secret into the secret store used by your client, CI job or service.
- Give the replacement any additional per-key permission the client requires, such as Subscription management.
- Update the client and verify a permitted request, such as the usage request documented in the API overview.
- Open the old key's detail view and choose Revoke key after all intended clients have migrated.
Rotating a Codity API key does not replace a GitLab PAT, reconnect Bitbucket or renew the CLI login session. Those credentials have different issuers and management controls.
Key Revocation
Revoke provider tokens in the provider's access-token settings, or remove GitHub App installation access when that integration should stop. For public API keys, use the key-management controls in API Keys. Check dependent integrations before removing a shared credential.
| Credential | Where to manage or revoke it | What to verify afterward |
|---|---|---|
| GitHub App access | The installed App's account/repository access in GitHub | The installation still includes every repository intended to remain connected. |
| GitLab PAT | The issuing GitLab account's access-token settings | Codity has a valid replacement for affected repository operations. |
| Azure DevOps PAT | The issuing account's personal-access-token settings | The selected organization's shared PAT is valid and has required rights. |
| Bitbucket OAuth access | The connected-app authorization in Bitbucket | Reauthorize through Codity when that connection should continue. |
| Public Codity API key | API Keys → key detail → Revoke key | Intended clients use a different active key. |
Removing an integration credential can interrupt reviews and other provider operations. For shared credentials, identify dependent workflows before a planned removal. A new browser sign-in is not sufficient evidence that those workflows recovered.
Common Auth-Related Failures
Sign-in expired: sign in again with the intended identity and select the correct account.
Stored token expired or invalid: replace it through the provider-specific control. Verify owner permissions and token expiration as well as scopes.
Insufficient permissions: read the operation's error. Check provider membership, active account, integration rights and Codity feature/admin access as applicable.
Diagnose the Failing Layer
| Symptom | Likely area to investigate | Verification |
|---|---|---|
| Cannot open the dashboard after authorization | Provider identity or dashboard session | Sign in with the intended identity and verify the selected account. |
| Dashboard opens but repositories fail to load | Stored provider credential, App access or account selection | Check the provider connection and an affected repository's membership/access. |
| Repository loads but Enable fails | Webhook rights or account authorization | Read the returned error; verify permission to configure provider notifications. |
| Reviews read code but cannot post feedback or fixes | Credential write rights or feature configuration | Check the failing operation, its feature setting and the provider's required permission. |
| A public API request is rejected | Codity API key, account eligibility or endpoint permission | Check the response and key status; provider-token rotation does not repair a Codity API key. |
| One teammate can rotate a shared PAT but another cannot | Ownership/admin rules for that saved connection | Ask the configuring user or an authorized account admin to perform the update. |
When contacting support, include the provider, selected account, failing action, time and non-sensitive error or request reference. Redact credentials and private content you are not authorized to share.

