Setting Up Jira Keys and Authentication

This guide covers how to obtain and configure all Jira authentication keys and credentials needed for ticket-mate.

Overview

ticket-mate requires authentication credentials to access your Jira instance. There are two main authentication modes:

1. Personal Access Token (PAT) - Simple, for local development and single-user scenarios
2. OAuth 2.0 - For production/SaaS with multi-user support

Quick Links

• Personal Access Token Setup - For local development
• OAuth 2.0 Setup - For production/company-managed apps
• Cloud ID Setup - For scoped API tokens
• Project Configuration - Setting up project keys
• Troubleshooting - Common issues and fixes

Personal Access Token (PAT) Setup

Step 1: Generate API Token

1. Go to Atlassian Account Security
2. Click "Create API token"
3. Give it a label (e.g., "ticket-mate-local-dev")
4. Click "Create"
5. Copy the token immediately - it's only shown once!
   • Token should be ~192 characters long
   • Format: ATATT3xFfGF0... (starts with ATATT3x)

Step 2: Get Your Base URL

Your Jira base URL is your Atlassian site URL:

• Format: https://your-site.atlassian.net
• Example: https://pamcms.atlassian.net

Step 3: Configure Environment Variables

Add to .env.local:

env
ATLASSIAN_BASE_URL=https://your-site.atlassian.net
ATLASSIAN_EMAIL=your-email@example.com
ATLASSIAN_API_KEY=ATATT3xFfGF0...your-192-character-token

Step 4: Verify Setup

Run the check command:

bash
tm env-check

You should see:

✅ ATLASSIAN_BASE_URL        = https://your-site.atlassian.net
✅ ATLASSIAN_EMAIL           = your-email@example.com
✅ ATLASSIAN_API_KEY         = ATATT3x***K9wq (length: 192)

Step 5: Test Connection

bash
tm check-permissions

This will show:

• Connection overview
• Your account information
• Project permissions

OAuth 2.0 Setup (For Company-Managed Apps)

For production deployments and company-managed applications, use OAuth 2.0.

Step 1: Create Atlassian App

1. Go to Atlassian Developer Console
2. Click "Create" → "New app"
3. Choose "OAuth 2.0 (3LO)" integration type
4. Fill in app details:
   • Name: ticket-mate (or your app name)
   • App logo: (optional)
   • App description: Integration for ticket-mate

Step 2: Configure OAuth Settings

1. In your app settings, go to "Authorization"

2. Set Callback URL:

   http://localhost:4000/api/auth/jira/callback
   

   (For production, use your actual domain)

3. Add Scopes (required permissions):

   • read:jira-work - Read Jira issues, projects, boards
   • write:jira-work - Create and update issues
   • read:jira-user - Read user information
   • offline_access - Refresh tokens

Step 3: Get Client Credentials

1. In your app settings, go to "Settings" → "App details"
2. Copy:
   • Client ID (e.g., j8yykR...)
   • Client Secret (click "Show" to reveal)

Step 4: Configure Environment Variables

Add to .env.local:

env
ATLASSIAN_AUTH_MODE=OAUTH
ATLASSIAN_CLIENT_ID=your-client-id
ATLASSIAN_CLIENT_SECRET=your-client-secret
ATLASSIAN_REDIRECT_URI=http://localhost:4000/api/auth/jira/callback

Step 5: User OAuth Flow

Users will connect their Jira accounts through the OAuth flow:

1. Navigate to the ticket-mate dashboard
2. Click "Connect Jira" or similar
3. Authorize the app
4. Tokens are stored per-user in the database

Note: In OAuth mode, cloudId is automatically stored per-user after the OAuth flow completes. You don't need to set ATLASSIAN_CLOUD_ID in environment variables.

Cloud ID Setup

Cloud ID is required when using scoped API tokens or Cloud API URLs.

When You Need Cloud ID

• Using scoped API tokens (long tokens starting with ATATT3x...)
• Projects not appearing with standard configuration
• Getting 403/404 errors when listing projects
• Using ATLASSIAN_USE_CLOUD_API=true

How to Find Your Cloud ID

Method 1: From Admin Console

1. Go to Atlassian Admin Console
2. Select your site
3. Cloud ID is shown in the URL or site settings
   • Format: f82a209c-ad3a-4c8c-b311-fc3bf6e584b5

Method 2: From API

bash
curl -u your-email@example.com:your-api-token \
  https://your-site.atlassian.net/rest/api/3/serverInfo

Look for deploymentId in the response.

Method 3: From Project Settings

1. Go to your Jira project (e.g., NOVA Project Settings)
2. Check the URL or project details
3. Cloud ID may be visible in network requests (use browser DevTools)

Configure Cloud ID

For PAT mode, add to .env.local:

env
ATLASSIAN_USE_CLOUD_API=true
ATLASSIAN_CLOUD_ID=f82a209c-ad3a-4c8c-b311-fc3bf6e584b5

Note: In OAuth mode, Cloud ID is automatically stored per-user and doesn't need to be set in env.

Project Configuration

Setting Default Project Key

The default project key is SPACE2. You can override it in several ways:

Option 1: CLI Flag (Recommended)

bash
tm check-permissions -p SPACE2
tm create-ticket -p SPACE2 -t "My ticket"

Option 2: Environment Variable

env
ATLASSIAN_PROJECT_KEY=SPACE2

Option 3: Config File

Create jira.json or ticket-mate.json:

json
{
  "projectKey": "SPACE2"
}

Project Access

Ensure you have the following permissions on your project:

• Browse Projects - View project details
• Create Issues - Create new tickets
• Administer Projects - (Optional) For advanced features
• Browse users and groups - (Optional) For user search

Check permissions:

bash
tm check-permissions -p SPACE2

Company-Managed Apps

For company-managed Atlassian apps:

Additional Requirements

1. App Approval: Company admins may need to approve the app
2. Scoped Permissions: Ensure your app has the right scopes
3. User Consent: Users may need to consent to app access

Admin Setup

1. Go to Atlassian Admin Console
2. Navigate to "Security" → "API tokens" or "OAuth apps"
3. Approve your app if needed
4. Configure allowed domains for OAuth redirects

Project-Specific Setup

For project-specific access (e.g., NOVA project):

1. Go to Project Settings
2. Ensure your user/service account has:
   • Project access
   • Required permissions (see above)
3. For OAuth apps, ensure the app is approved for the project

Troubleshooting

"Authentication failed" (401)

Problem: Invalid API token or credentials

Solutions:

1. Verify API token is ~192 characters (not 75)

   bash
   tm env-check

2. Regenerate API token at Atlassian API Tokens
3. Check ATLASSIAN_EMAIL matches your Atlassian account email
4. Verify ATLASSIAN_BASE_URL is correct

"No projects found"

Problem: Token doesn't have project access or wrong API endpoint

Solutions:

1. Enable Cloud API mode:

   env
   ATLASSIAN_USE_CLOUD_API=true
   ATLASSIAN_CLOUD_ID=your-cloud-id

2. Check project permissions:

   bash
   tm check-permissions -p SPACE2

3. Verify you have "Browse Projects" permission

"Project not found" (404)

Problem: Project key doesn't exist or no access

Solutions:

1. Verify project key is correct (case-sensitive)
2. Check you have access to the project
3. List accessible projects:

   bash
   tm ls-projects

OAuth "Invalid client" error

Problem: Wrong client ID/secret or app not approved

Solutions:

1. Verify ATLASSIAN_CLIENT_ID and ATLASSIAN_CLIENT_SECRET in .env.local
2. Check callback URL matches app configuration
3. Ensure app is approved by company admin (for company-managed apps)
4. Verify scopes are correct

API Token Too Short

Problem: Token is only 75 characters instead of 192

Solution: You may have an old token format. Generate a new one:

1. Go to Atlassian API Tokens
2. Delete old token
3. Create new token
4. Update .env.local

Related Documentation

• Environment Variables Guide - Complete list of all env vars
• Authentication Guide - Detailed auth mode comparison
• OAuth Setup Guide - Step-by-step OAuth configuration
• Permissions & Access - Required Jira permissions
• Cloud API Setup - Cloud API configuration
• Quick Permission Fix - Quick fixes for permission issues
• Jira Setup Guide - General Jira configuration

Quick Reference

Required for PAT Mode

• ATLASSIAN_BASE_URL - Your Jira site URL
• ATLASSIAN_EMAIL - Your Atlassian email
• ATLASSIAN_API_KEY - ~192 character token from API Tokens

Required for OAuth Mode

• ATLASSIAN_CLIENT_ID - From Developer Console
• ATLASSIAN_CLIENT_SECRET - From Developer Console
• ATLASSIAN_REDIRECT_URI - OAuth callback URL

Optional

• ATLASSIAN_CLOUD_ID - For Cloud API (find at Admin Console)
• ATLASSIAN_PROJECT_KEY - Default project (defaults to SPACE2)
• ATLASSIAN_USE_CLOUD_API - Enable Cloud API mode

Getting Help

If you're stuck:

1. Check environment: tm env-check
2. Test connection: tm check-permissions
3. List projects: tm ls-projects
4. Debug mode: tm env-debug

For company-managed apps, contact your Atlassian admin for:

• App approval
• Project access
• Permission grants