Atlassian Mcp

# Authentication Patterns

---

## Authentication Methods Overview

| Method | Platform | Use Case | Security Level |
|--------|----------|----------|----------------|
| OAuth 2.1 | Cloud | User-facing apps, integrations | Highest |
| API Token | Cloud | Personal automation, scripts | Medium |
| PAT | Server/DC | Server integrations | Medium |
| Basic Auth | Legacy | Deprecated, avoid | Low |

## OAuth 2.1 (Atlassian Cloud)

### Authorization Code Flow

For applications that act on behalf of users.

**Step 1: Register Your App**

1. Go to [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
2. Create new app
3. Configure OAuth 2.0 (3LO)
4. Add callback URL
5. Request necessary scopes

**Step 2: Authorization Request**

```typescript
const authUrl = new URL('https://auth.atlassian.com/authorize');
authUrl.searchParams.set('audience', 'api.atlassian.com');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('scope', 'read:jira-work write:jira-work read:confluence-content.all write:confluence-content');
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('state', generateState());
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('prompt', 'consent');

// Redirect user to authUrl.toString()
```

**Step 3: Exchange Code for Token**

```typescript
async function exchangeCodeForToken(code: string): Promise<TokenResponse> {
  const response = await fetch('https://auth.atlassian.com/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      redirect_uri: REDIRECT_URI,
    }),
  });

  if (!response.ok) {
    throw new Error(`Token exchange failed: ${response.statusText}`);
  }

  return response.json();
}

interface TokenResponse {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  scope: string;
  token_type: 'Bearer';
}
```

**Step 4: Refresh Token**

```typescript
async function refreshAccessToken(refreshToken: string): Promise<TokenResponse> {
  const response = await fetch('https://auth.atlassian.com/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
    }),
  });

  return response.json();
}
```

**Step 5: Get Accessible Resources**

```typescript
async function getAccessibleResources(accessToken: string): Promise<Resource[]> {
  const response = await fetch(
    'https://api.atlassian.com/oauth/token/accessible-resources',
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Accept: 'application/json',
      },
    }
  );

  return response.json();
}

interface Resource {
  id: string;        // Cloud ID
  name: string;      // Site name
  url: string;       // https://your-site.atlassian.net
  scopes: string[];
  avatarUrl: string;
}
```

### OAuth Scopes Reference

**Jira Scopes:**

| Scope | Description |
|-------|-------------|
| `read:jira-work` | Read issues, projects, boards |
| `write:jira-work` | Create/update issues |
| `manage:jira-project` | Manage project settings |
| `manage:jira-configuration` | Manage global settings |
| `read:jira-user` | Read user profiles |
| `manage:jira-data-provider` | Data provider integrations |

**Confluence Scopes:**

| Scope | Description |
|-------|-------------|
| `read:confluence-content.all` | Read all content |
| `write:confluence-content` | Create/update content |
| `read:confluence-content.summary` | Read content summaries |
| `read:confluence-space.summary` | Read space summaries |
| `write:confluence-space` | Create/manage spaces |
| `read:confluence-user` | Read user profiles |

**Granular Scopes (v2):**

```
read:issue-details:jira
writ