API Keys and Tokens

This document explains how authentication works in Codity and how to manage API keys and tokens.

Authentication Overview

Codity uses different authentication methods depending on your provider:

  • GitHub: GitHub App (automatic token management)
  • GitLab: OAuth + Personal Access Token (manual token management)
  • Azure DevOps: OAuth + Personal Access Token (manual token management)

How Authentication Works

GitHub

GitHub uses a GitHub App model:

  1. OAuth sign-in: You sign in to Codity using GitHub OAuth
  2. App installation: You install the Codity GitHub App on your organization/account
  3. Automatic tokens: Codity automatically manages installation tokens
  4. No manual configuration: You don't need to create or manage tokens

Key points:

  • Tokens are automatically generated and rotated
  • No expiration to manage
  • Higher rate limits than personal tokens
  • Scoped to installed repositories only

GitLab

GitLab uses OAuth + Personal Access Token:

  1. OAuth sign-in: You sign in to Codity using GitLab OAuth (grants basic access)
  2. Token creation: You create a Personal Access Token in GitLab
  3. Token configuration: You configure the token in Codity Settings
  4. Manual management: You must update tokens when they expire

Key points:

  • Tokens must be manually created in GitLab
  • Tokens have expiration dates
  • You must update tokens before expiration
  • Tokens are encrypted and stored securely

Azure DevOps

Azure DevOps uses OAuth + Personal Access Token:

  1. OAuth sign-in: You sign in to Codity using Azure DevOps OAuth (grants basic access)
  2. Token creation: You create a Personal Access Token in Azure DevOps
  3. Token configuration: You configure the token in Codity Settings
  4. Manual management: You must update tokens when they expire

Key points:

  • Tokens must be manually created in Azure DevOps
  • Tokens are organization-specific
  • Tokens have expiration dates
  • You must update tokens before expiration
  • Tokens are encrypted and stored securely

Generating Tokens

GitLab Personal Access Token

  1. Go to GitLab → Settings → Access Tokens
  2. Click "Add new token"
  3. Configure:
    • Token name: "Codity Access" (or similar)
    • Expiration date: Recommended 90 days
    • Scopes: Select:
      • api
      • read_repository
      • write_repository
      • read_user
  4. Click "Create personal access token"
  5. Copy the token immediately (you won't see it again)
  6. Paste it into Codity Settings → GitLab Token

Azure DevOps Personal Access Token

  1. Go to Azure DevOps → User Settings → Personal Access Tokens
  2. Click "New Token"
  3. Configure:
    • Name: "Codity Access" (or similar)
    • Organization: Select your organization
    • Expiration: Recommended 90 days
    • Scopes: Select:
      • Code (Read & Write)
      • Pull Requests (Read & Write)
      • Project and Team (Read)
      • User Profile (Read)
  4. Click "Create"
  5. Copy the token immediately (you won't see it again)
  6. Paste it into Codity Settings → Azure DevOps Token

Where Tokens Are Used

Tokens are used for:

  • Reading repository contents: To analyze code changes
  • Reading pull requests/merge requests: To review changes
  • Posting comments: To provide feedback
  • Creating branches and PRs: For test generation
  • Registering webhooks: To receive notifications

Safe Storage Practices

In Codity

  • Encryption: All tokens are encrypted at rest
  • Secure transmission: Tokens are transmitted over HTTPS only
  • Access control: Only Codity services can access tokens
  • No logging: Tokens are never logged

In Your Systems

  • Never commit tokens: Never commit tokens to version control
  • Use environment variables: Store tokens in environment variables, not code
  • Rotate regularly: Update tokens before expiration
  • Revoke compromised tokens: Immediately revoke and create new tokens if compromised

Token Rotation

When to Rotate

  • Before expiration: Update tokens 1-2 weeks before expiration
  • After security incident: Rotate immediately if token may be compromised
  • When permissions change: Rotate if you need different scopes
  • Regularly: Consider rotating every 90 days as a security best practice

How to Rotate

  1. Create new token: Follow the token creation steps above
  2. Update in Codity: Go to Settings → [Provider] Token → Update
  3. Verify functionality: Test that reviews still work
  4. Revoke old token: Delete the old token in your provider's settings

Rotation Impact

  • Minimal downtime: Reviews may be delayed by a few minutes during rotation
  • No data loss: All historical data remains intact
  • Seamless transition: New token takes effect immediately

Key Revocation

When to Revoke

  • Token compromised: Immediately revoke if token is exposed
  • Employee departure: Revoke tokens when team members leave
  • Permission changes: Revoke if permissions are no longer needed
  • Security audit: Revoke unused or unnecessary tokens

How to Revoke

GitHub:

  • Uninstall the GitHub App (revokes all tokens)
  • Or modify app permissions

GitLab:

  • Go to Settings → Access Tokens
  • Find the token and click "Revoke"

Azure DevOps:

  • Go to User Settings → Personal Access Tokens
  • Find the token and click "Revoke"

After Revocation

  • Immediate effect: Revocation takes effect immediately
  • Service interruption: Reviews will fail until new token is configured
  • No data loss: Historical data remains intact

What You Should Never Expose

Never expose these:

  • Personal Access Tokens: Treat PATs like passwords
  • API keys: Any API keys used by Codity
  • Webhook secrets: Webhook secret tokens
  • Session tokens: Authentication session tokens

Safe to share:

  • Repository names: Repository names are public information
  • Organization names: Organization names are public information
  • Review comments: Review comments are visible in PRs/MRs (as intended)

"Authentication Failed"

Symptoms:

  • Cannot sign in
  • "Invalid credentials" error

Causes:

  • OAuth session expired
  • Provider account access revoked
  • Provider authentication error

How to Fix:

  1. Sign out and sign in again
  2. Check provider account access
  3. Verify OAuth permissions

"Token Expired"

Symptoms:

  • Reviews fail with "token expired" error
  • Cannot access repositories

Causes:

  • Personal Access Token expired
  • Token not updated before expiration

How to Fix:

  1. Create new token in provider
  2. Update token in Codity Settings
  3. Verify functionality

"Insufficient Permissions"

Symptoms:

  • "Access denied" errors
  • Cannot read repositories or post comments

Causes:

  • Token missing required scopes
  • Repository access not granted
  • Organization restrictions

How to Fix:

  1. Verify token has required scopes
  2. Check repository access permissions
  3. Review organization settings

Best Practices

  1. Use strong tokens: Generate tokens with appropriate expiration
  2. Rotate regularly: Update tokens before expiration
  3. Monitor usage: Review token usage regularly
  4. Revoke unused tokens: Remove tokens that are no longer needed
  5. Document tokens: Keep track of token purposes and expiration dates
  6. Test after changes: Verify functionality after token updates