How to Use Bitbucket (3 Auth Modes) Effectively
Three authentication methods for flexible enterprise access. App password for personal workflows. API token for service accounts. Bearer auth for OAuth2 integration.
Why multiple authentication modes matter
Enterprise teams have different authentication needs. A developer on a laptop needs different access patterns than a service running in production.
Bitbucket supports three authentication modes. WalnutAI works with all three. You choose based on your security posture and workflow.
No one-size-fits-all. Flexible authentication for flexible enterprises
The three authentication modes
App Password (Personal Use) App password is the simplest. You create a password specifically for WalnutAI. Best for: developers running WalnutAI locally, personal workflows, development environments. Security: lower than API tokens, but scoped to your Bitbucket account.
API Token (Service Accounts) API token is for service accounts and CI/CD systems. Long-lived, scoped, revocable. Best for: service accounts in production, CI/CD pipelines, unattended automation. Security: higher than app passwords, audit trail included.
Bearer Auth (OAuth2) Bearer auth uses OAuth2 tokens. Modern, federated, short-lived by default. Best for: multi-tenant systems, delegated access, enterprise SSO integration. Security: highest, requires OAuth2 provider, time-limited tokens.
Authentication Mode Comparison
Choose your mode based on use case and security requirements:
Quick comparison: App Password:
- Setup time: 2 minutes
- Token lifetime: indefinite (until revoked)
- Audit trail: basic
- Use case: dev laptop, personal workflows
API Token:
- Setup time: 5 minutes
- Token lifetime: configurable, typically 1 year
- Audit trail: detailed
- Use case: service account, CI/CD, production
Bearer Auth:
- Setup time: 15 minutes (requires OAuth2 setup)
- Token lifetime: short-lived (1 hour default)
- Audit trail: comprehensive
- Use case: multi-tenant, SSO, enterprise
Setup: App Password
Step 1: Create app password in Bitbucket
Log into Bitbucket. Go to Personal Settings > App passwords > Create app password.
Give it a name: 'WalnutAI'.
Select scopes:
account: read
repository: read
pullrequest: read, write
Bitbucket generates a password. Copy it immediately (you cannot see it again).
Step 2: Configure WalnutAI
In WalnutAI settings, go to Integrations > Bitbucket.
Select 'App Password' as auth mode.
Configuration: Bitbucket workspace: [your workspace]
Username: [your Bitbucket username]
App password: [paste the password from Bitbucket]
Save. WalnutAI tests the connection.
Step 3: Verify
Try gap analysis on a Bitbucket repository. If it works, authentication is successful.
Setup: API Token
Step 1: Create API token for service account
Log into Bitbucket as the service account (or as admin acting on behalf of service account).
Go to Personal Settings > App passwords > Create app password (yes, Bitbucket calls them the same thing).
Name it 'WalnutAI Service'.
Select scopes:
account: read
repository: read, admin
pullrequest: read, write
pipeline: read, write
Copy the token.
Step 2: Configure WalnutAI with service account
In WalnutAI settings, go to Integrations > Bitbucket.
Select 'API Token' as auth mode.
Configuration: Bitbucket workspace: [workspace name]
Service account username: [service account username]
API token: [paste the token from Bitbucket]
Save. WalnutAI tests the connection using service account credentials.
Step 3: Grant service account access
Make sure the service account has access to the repositories you want to analyze.
In Bitbucket repository settings, add the service account as a 'Reader' or 'Developer'.
Step 4: Set up rotation schedule
API tokens should be rotated regularly (every 90-180 days for production).
Set a calendar reminder to rotate the token. Generate new token, update WalnutAI settings, revoke old token.
Setup: Bearer Auth (OAuth2)
Step 1: Register OAuth2 application in Bitbucket As workspace admin, go to Workspace Settings > OAuth consumers. Click 'Create consumer'. OAuth2 consumer settings: Name: WalnutAI Callback URL: WalnutAI - Project AssistantRedirect URL: WalnutAI - Project Assistant
Select permissions:
account: read
repository: read
pullrequest: read, write Bitbucket generates client ID and client secret. Copy both.
Step 2: Configure WalnutAI with OAuth2 credentials
In WalnutAI settings, go to Integrations > Bitbucket.
Select 'Bearer Auth (OAuth2)' as auth mode.
Configuration: OAuth2 client ID: [from Bitbucket]
OAuth2 client secret: [from Bitbucket]
Bitbucket workspace: [workspace name]
Save. WalnutAI is now configured for OAuth2.
Step 3: Authenticate
First time you run an analysis, WalnutAI redirects you to Bitbucket.
'WalnutAI is requesting access to your Bitbucket account.'
Click 'Authorize'. You are redirected back to WalnutAI.
Authorization is complete. WalnutAI now has an access token (short-lived, auto-refreshed).
Security best practices
For app passwords (dev use)Rotate every 30 days
Use on personal machines only, not shared machines
Revoke immediately if laptop is lost or access is suspected compromised
Store in a secret manager (HashiCorp Vault, AWS Secrets Manager)
Never commit to code or config files
Rotate every 90-180 days
Use least privilege scopes (read-only when possible)
Monitor token usage in Bitbucket audit logs
Client secret never leaves WalnutAI backend
Access tokens are auto-refreshed by WalnutAI
User-granted permissions are auditable in Bitbucket
Revoking access in Bitbucket immediately affects WalnutAI
