Skip to main content

​
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 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
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 -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 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 -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

  • Never commit tokens to version control
  • Use secret management systems (Vault, Secrets Manager)
  • Rotate tokens regularly
  • Use environment variables or secure files
  • 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
  • Always use HTTPS for API requests
  • Validate TLS certificates
  • Consider network policies and firewalls
  • Use VPN or private networks when possible
  • 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 expiredSolution: Obtain a new token via login
​
PERMISSION_DENIED (403)
error
Authenticated but insufficient permissionsSolution: 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

Build docs developers (and LLMs) love

Get started for freeTalk to us