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:

curl -H "Authorization: Bearer $TOKEN" \
  https://argocd-server/api/v1/applications

Token Types

User Tokens

User tokens are obtained by logging in through the Session API.

# 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

Service Account Tokens

Long-lived tokens for automation and CI/CD.

# 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

Project Tokens

Scoped tokens limited to specific project permissions.

# 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

Cookie-Based Authentication

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

# 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.

cURL

curl -X POST https://argocd-server/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-password"
  }'

Request

username · string · required

Username for authentication

password · string · required

Password for authentication

token · string

SSO token (alternative to username/password)

Response

token · string

JWT token for subsequent API requests

Example Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get User Info

Retrieve information about the currently authenticated user.

cURL

curl https://argocd-server/api/v1/session/userinfo \
  -H "Authorization: Bearer $TOKEN"

Response

loggedIn · boolean

Whether the user is currently logged in

username · string

Username of the authenticated user

iss · string

Token issuer (e.g., “argocd” or SSO provider)

groups · string[]

List of groups the user belongs to

Example Response:

{
  "loggedIn": true,
  "username": "admin",
  "iss": "argocd",
  "groups": ["admin"]
}

Delete Session (Logout)

Invalidate the current session.

cURL

curl -X DELETE https://argocd-server/api/v1/session \
  -H "Authorization: Bearer $TOKEN"

Project Tokens

Project tokens provide scoped access limited to specific projects.

Create Project Token

Generate a new token for a project role.

POST /api/v1/projects/{project}/roles/{role}/token

project · string · required

Project name

role · string · required

Role name within the project

description · string

Human-readable description of the token

expiresIn · int64

Token lifetime in seconds (0 for no expiration)

id · string

Custom identifier for the token

Example Request:

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:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Delete Project Token

Revoke a project token.

DELETE /api/v1/projects/{project}/roles/{role}/token/{iat}

project · string · required

Project name

role · string · required

Role name

iat · int64 · required

Token issued-at timestamp

id · string

Token ID (alternative to iat)

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

# 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

Token Storage

• Never commit tokens to version control
• Use secret management systems (Vault, Secrets Manager)
• Rotate tokens regularly
• Use environment variables or secure files

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

Network Security

• Always use HTTPS for API requests
• Validate TLS certificates
• Consider network policies and firewalls
• Use VPN or private networks when possible

Monitoring

• Monitor token usage and creation
• Set up alerts for suspicious activity
• Audit token access regularly
• Revoke unused tokens

Authentication Errors

Common Error Codes

UNAUTHENTICATED (401) · error

No valid authentication provided or token expired

Solution: Obtain a new token via login

PERMISSION_DENIED (403) · error

Authenticated but insufficient permissions

Solution: Check RBAC policies and token scope

Error Response Example

{
  "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):

# Decode token (header and payload)
echo $TOKEN | cut -d'.' -f2 | base64 -d | jq

Token Claims:

{
  "iss": "argocd",
  "sub": "admin",
  "iat": 1709568000,
  "exp": 1709654400,
  "groups": ["admin"]
}

Next Steps

Application API

Use your token to manage applications

Project API

Create and manage project tokens