> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Authentication methods for Argo CD API access including bearer tokens and cookies

## Overview

Argo CD API supports multiple authentication methods for different use cases. All API requests (except session creation) must include valid authentication credentials.

## Authentication Methods

### Bearer Token Authentication

The recommended method for API access. Include the token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  https://argocd-server/api/v1/applications
```

#### Token Types

<Tabs>
  <Tab title="User Tokens">
    User tokens are obtained by logging in through the Session API.

    ```bash theme={null}
    # Login and get token
    TOKEN=$(curl -X POST https://argocd-server/api/v1/session \
      -d '{"username":"admin","password":"password"}' | jq -r .token)

    # Use token
    curl -H "Authorization: Bearer $TOKEN" \
      https://argocd-server/api/v1/applications
    ```
  </Tab>

  <Tab title="Service Account Tokens">
    Long-lived tokens for automation and CI/CD.

    ```bash theme={null}
    # Create service account token via CLI
    argocd account generate-token --account myapp-ci

    # Use token
    curl -H "Authorization: Bearer $SERVICE_TOKEN" \
      https://argocd-server/api/v1/applications
    ```
  </Tab>

  <Tab title="Project Tokens">
    Scoped tokens limited to specific project permissions.

    ```bash theme={null}
    # Create project token via API
    curl -X POST https://argocd-server/api/v1/projects/myproject/roles/ci-role/token \
      -H "Authorization: Bearer $ADMIN_TOKEN" \
      -d '{"expiresIn":2592000}'

    # Use project token
    curl -H "Authorization: Bearer $PROJECT_TOKEN" \
      https://argocd-server/api/v1/applications?projects=myproject
    ```
  </Tab>
</Tabs>

### Cookie-Based Authentication

Used primarily by the web UI. The session cookie is automatically set when logging in via the browser.

```bash theme={null}
# Login returns a cookie
curl -c cookies.txt -X POST https://argocd-server/api/v1/session \
  -d '{"username":"admin","password":"password"}'

# Subsequent requests use the cookie
curl -b cookies.txt https://argocd-server/api/v1/applications
```

## Session Service API

### Create Session (Login)

Establish a new authenticated session.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://argocd-server/api/v1/session \
    -H "Content-Type: application/json" \
    -d '{
      "username": "admin",
      "password": "your-password"
    }'
  ```

  ```go Go theme={null}
  import sessionpkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/session"

  sessionClient := sessionpkg.NewSessionServiceClient(conn)
  resp, err := sessionClient.Create(ctx, &sessionpkg.SessionCreateRequest{
      Username: "admin",
      Password: "password",
  })
  token := resp.Token
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://argocd-server/api/v1/session",
      json={"username": "admin", "password": "password"}
  )
  token = response.json()["token"]
  ```
</CodeGroup>

#### Request

<ParamField path="username" type="string" required>
  Username for authentication
</ParamField>

<ParamField path="password" type="string" required>
  Password for authentication
</ParamField>

<ParamField path="token" type="string">
  SSO token (alternative to username/password)
</ParamField>

#### Response

<ResponseField name="token" type="string">
  JWT token for subsequent API requests
</ResponseField>

**Example Response:**

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Get User Info

Retrieve information about the currently authenticated user.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://argocd-server/api/v1/session/userinfo \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  userInfo, err := sessionClient.GetUserInfo(ctx, &sessionpkg.GetUserInfoRequest{})
  ```
</CodeGroup>

#### Response

<ResponseField name="loggedIn" type="boolean">
  Whether the user is currently logged in
</ResponseField>

<ResponseField name="username" type="string">
  Username of the authenticated user
</ResponseField>

<ResponseField name="iss" type="string">
  Token issuer (e.g., "argocd" or SSO provider)
</ResponseField>

<ResponseField name="groups" type="string[]">
  List of groups the user belongs to
</ResponseField>

**Example Response:**

```json theme={null}
{
  "loggedIn": true,
  "username": "admin",
  "iss": "argocd",
  "groups": ["admin"]
}
```

### Delete Session (Logout)

Invalidate the current session.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://argocd-server/api/v1/session \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  _, err := sessionClient.Delete(ctx, &sessionpkg.SessionDeleteRequest{})
  ```
</CodeGroup>

## Project Tokens

Project tokens provide scoped access limited to specific projects.

### Create Project Token

Generate a new token for a project role.

```bash theme={null}
POST /api/v1/projects/{project}/roles/{role}/token
```

<ParamField path="project" type="string" required>
  Project name
</ParamField>

<ParamField path="role" type="string" required>
  Role name within the project
</ParamField>

<ParamField body="description" type="string">
  Human-readable description of the token
</ParamField>

<ParamField body="expiresIn" type="int64">
  Token lifetime in seconds (0 for no expiration)
</ParamField>

<ParamField body="id" type="string">
  Custom identifier for the token
</ParamField>

**Example Request:**

```bash theme={null}
curl -X POST https://argocd-server/api/v1/projects/myproject/roles/ci-role/token \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "description": "CI/CD Pipeline Token",
    "expiresIn": 2592000
  }'
```

**Example Response:**

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Delete Project Token

Revoke a project token.

```bash theme={null}
DELETE /api/v1/projects/{project}/roles/{role}/token/{iat}
```

<ParamField path="project" type="string" required>
  Project name
</ParamField>

<ParamField path="role" type="string" required>
  Role name
</ParamField>

<ParamField path="iat" type="int64" required>
  Token issued-at timestamp
</ParamField>

<ParamField query="id" type="string">
  Token ID (alternative to iat)
</ParamField>

## SSO Authentication

For SSO-enabled Argo CD installations:

1. Redirect to SSO provider
2. Complete SSO authentication flow
3. Receive token from callback
4. Use token for API access

```bash theme={null}
# Get SSO login URL from settings
curl https://argocd-server/api/v1/settings

# After SSO flow, use the returned token
curl -H "Authorization: Bearer $SSO_TOKEN" \
  https://argocd-server/api/v1/applications
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Token Storage">
    * Never commit tokens to version control
    * Use secret management systems (Vault, Secrets Manager)
    * Rotate tokens regularly
    * Use environment variables or secure files
  </Accordion>

  <Accordion title="Token Scope">
    * Use project tokens for project-specific automation
    * Limit token permissions to minimum required
    * Create separate tokens for different automation tasks
    * Set expiration times for temporary access
  </Accordion>

  <Accordion title="Network Security">
    * Always use HTTPS for API requests
    * Validate TLS certificates
    * Consider network policies and firewalls
    * Use VPN or private networks when possible
  </Accordion>

  <Accordion title="Monitoring">
    * Monitor token usage and creation
    * Set up alerts for suspicious activity
    * Audit token access regularly
    * Revoke unused tokens
  </Accordion>
</AccordionGroup>

## Authentication Errors

### Common Error Codes

<ResponseField name="UNAUTHENTICATED (401)" type="error">
  No valid authentication provided or token expired

  **Solution:** Obtain a new token via login
</ResponseField>

<ResponseField name="PERMISSION_DENIED (403)" type="error">
  Authenticated but insufficient permissions

  **Solution:** Check RBAC policies and token scope
</ResponseField>

### Error Response Example

```json theme={null}
{
  "error": "rpc error: code = Unauthenticated desc = no session information",
  "code": 16
}
```

## Token Validation

JWT tokens can be decoded (but not verified without the server secret):

```bash theme={null}
# Decode token (header and payload)
echo $TOKEN | cut -d'.' -f2 | base64 -d | jq
```

**Token Claims:**

```json theme={null}
{
  "iss": "argocd",
  "sub": "admin",
  "iat": 1709568000,
  "exp": 1709654400,
  "groups": ["admin"]
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Application API" icon="rocket" href="/api/application">
    Use your token to manage applications
  </Card>

  <Card title="Project API" icon="folder" href="/api/appproject">
    Create and manage project tokens
  </Card>
</CardGroup>