AppProject API - Argo CD

Overview

The Project Service API manages AppProject resources, which provide logical grouping and access control for Applications. Projects define where apps can deploy, what can be deployed, and who can access them. Base Path: /api/v1/projects gRPC Service: project.ProjectService

AppProject Resource

An AppProject provides multi-tenancy and RBAC controls for Applications.

AppProject Spec

string[]

required

Allowed source repositories (supports wildcards)

sourceRepos:
- 'https://github.com/myorg/*'
- 'https://helm.example.com'

ApplicationDestination[]

required

Allowed deployment destinations

Show ApplicationDestination fields

string

Kubernetes server URL (supports wildcards)

string

Cluster name (alternative to server)

string

Target namespace (supports wildcards)

ResourceSelector[]

Allowed cluster-scoped resources

Show ResourceSelector fields

string

API group (empty for core)

string

Resource kind

ResourceSelector[]

Denied cluster-scoped resources

ResourceSelector[]

Allowed namespace-scoped resources

ResourceSelector[]

Denied namespace-scoped resources

ProjectRole[]

RBAC roles for the project

Show ProjectRole fields

string

required

Role name

string

Role description

string[]

required

RBAC policies (Casbin format)

string[]

SSO groups bound to this role

JWTToken[]

JWT tokens for automation

SyncWindow[]

Time windows for controlling sync operations

string[]

Namespaces where Applications can be created

Example AppProject

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  description: Production applications
  
  # Allowed sources
  sourceRepos:
  - 'https://github.com/myorg/*'
  - 'https://charts.helm.sh/stable'
  
  # Allowed destinations
  destinations:
  - namespace: 'prod-*'
    server: https://kubernetes.default.svc
  - namespace: production
    server: 'https://prod-*.example.com'
  
  # Cluster resources
  clusterResourceWhitelist:
  - group: ''
    kind: Namespace
  
  # Namespace resources  
  namespaceResourceBlacklist:
  - group: ''
    kind: ResourceQuota
  
  # Roles
  roles:
  - name: ci-role
    description: CI/CD automation
    policies:
    - p, proj:production:ci-role, applications, sync, production/*, allow
    - p, proj:production:ci-role, applications, get, production/*, allow
  
  - name: developer
    description: Developer access
    policies:
    - p, proj:production:developer, applications, get, production/*, allow
    groups:
    - myorg:developers

API Operations

List Projects

Retrieve list of projects.

GET /api/v1/projects

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

import projectpkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/project"

projectClient := projectpkg.NewProjectServiceClient(conn)
projects, err := projectClient.List(ctx, &projectpkg.ProjectQuery{})

import requests

response = requests.get(
    "https://argocd-server/api/v1/projects",
    headers={"Authorization": f"Bearer {token}"}
)
projects = response.json()

Get Project

Retrieve a specific project.

GET /api/v1/projects/{name}

string

required

Project name

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

project, err := projectClient.Get(ctx, &projectpkg.ProjectQuery{
    Name: "production",
})

Get Detailed Project

Get project with global projects and scoped resources.

GET /api/v1/projects/{name}/detailed

string

required

Project name

Response includes:

Project definition
Global projects
Scoped repositories
Scoped clusters

Create Project

Create a new project.

POST /api/v1/projects

AppProject

required

Complete AppProject resource

boolean

Update if already exists (default: false)

curl -X POST https://argocd-server/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {
      "metadata": {
        "name": "production"
      },
      "spec": {
        "description": "Production applications",
        "sourceRepos": ["*"],
        "destinations": [
          {
            "namespace": "*",
            "server": "https://kubernetes.default.svc"
          }
        ],
        "clusterResourceWhitelist": [
          {"group": "", "kind": "Namespace"}
        ]
      }
    }
  }'

project, err := projectClient.Create(ctx, &projectpkg.ProjectCreateRequest{
    Project: &v1alpha1.AppProject{
        ObjectMeta: metav1.ObjectMeta{
            Name: "production",
        },
        Spec: v1alpha1.AppProjectSpec{
            SourceRepos: []string{"*"},
            Destinations: []v1alpha1.ApplicationDestination{
                {
                    Server:    "https://kubernetes.default.svc",
                    Namespace: "*",
                },
            },
        },
    },
})

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  description: Production applications
  sourceRepos:
  - '*'
  destinations:
  - namespace: '*'
    server: https://kubernetes.default.svc
EOF

Update Project

Update an existing project.

PUT /api/v1/projects/{project.metadata.name}

AppProject

required

Updated AppProject resource

Delete Project

Delete a project.

DELETE /api/v1/projects/{name}

string

required

Project name

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

_, err := projectClient.Delete(ctx, &projectpkg.ProjectQuery{
    Name: "production",
})

Token Management

Create Project Token

Generate a JWT token for a project role.

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

string

required

Project name

string

required

Role name

string

Token description

int64

Token lifetime in seconds (0 = no expiration)

string

Custom token identifier

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

tokenResp, err := projectClient.CreateToken(ctx, &projectpkg.ProjectTokenCreateRequest{
    Project:     "production",
    Role:        "ci-role",
    Description: "CI Pipeline Token",
    ExpiresIn:   2592000, // 30 days
})
token := tokenResp.Token

Response:

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

Delete Project Token

Revoke a project token.

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

string

required

Project name

string

required

Role name

int64

required

Token issued-at timestamp

string

Token ID (alternative to iat)

RBAC Policies

Project roles use Casbin policy syntax:

p, <subject>, <resource>, <action>, <object>, <effect>

Policy Components

subject: proj:<project>:<role>
resource: applications, clusters, repositories, etc.
action: get, create, update, delete, sync, override, action/*
object: <project>/<application> or <project>/*
effect: allow or deny

Policy Examples

roles:
- name: ci-role
  policies:
  # Allow sync on all apps in project
  - p, proj:production:ci-role, applications, sync, production/*, allow
  
  # Allow get on all apps
  - p, proj:production:ci-role, applications, get, production/*, allow
  
  # Deny delete operations
  - p, proj:production:ci-role, applications, delete, production/*, deny

- name: admin
  policies:
  # Full access to project
  - p, proj:production:admin, applications, *, production/*, allow
  - p, proj:production:admin, repositories, *, production/*, allow
  - p, proj:production:admin, clusters, get, *, allow

Sync Windows

Control when applications can be synced.

Get Sync Windows

Get active and assigned sync windows for a project.

GET /api/v1/projects/{name}/syncwindows

string

required

Project name

Response:

{
  "windows": [
    {
      "kind": "allow",
      "schedule": "0 22 * * *",
      "duration": "1h",
      "applications": ["*"],
      "manualSync": true
    }
  ]
}

Sync Window Configuration

syncWindows:
- kind: allow
  schedule: '0 22 * * *'  # 10 PM daily
  duration: 1h
  applications:
  - '*'
  manualSync: true
  
- kind: deny
  schedule: '0 0 * * 0'   # Sunday midnight
  duration: 24h
  applications:
  - 'production-*'
  manualSync: false

Events & Monitoring

List Project Events

Get Kubernetes events for a project.

GET /api/v1/projects/{name}/events

string

required

Project name

List Project Links

Get deep links configured for the project.

GET /api/v1/projects/{name}/links

Global Projects

Global projects provide shared configuration.

Get Global Projects

Get global projects for a project.

GET /api/v1/projects/{name}/globalprojects

string

required

Project name

Resource Restrictions

Allow All Resources

clusterResourceWhitelist:
- group: '*'
  kind: '*'

Specific Resource Types

namespaceResourceWhitelist:
- group: 'apps'
  kind: Deployment
- group: ''
  kind: Service
- group: ''
  kind: ConfigMap

Deny Specific Resources

namespaceResourceBlacklist:
- group: ''
  kind: ResourceQuota
- group: ''
  kind: LimitRange

Wildcard Patterns

Source Repositories

sourceRepos:
- 'https://github.com/myorg/*'        # All repos in org
- 'https://github.com/myorg/app-*'    # Repos starting with app-
- '*'                                  # All repositories

Destinations

destinations:
- namespace: 'prod-*'                 # Namespaces starting with prod-
  server: 'https://kubernetes.default.svc'
- namespace: '*'
  server: 'https://prod-*.example.com' # Cluster URLs matching pattern

Next Steps

Application API

Create applications in projects

Cluster API

Configure destination clusters

Repository API

Configure source repositories

​Overview

​AppProject Resource

​AppProject Spec

​Example AppProject

​API Operations

​List Projects

​Get Project

​Get Detailed Project

​Create Project

​Update Project

​Delete Project

​Token Management

​Create Project Token

​Delete Project Token

​RBAC Policies

​Policy Components

​Policy Examples

​Sync Windows

​Get Sync Windows

​Sync Window Configuration

​Events & Monitoring

​List Project Events

​List Project Links

​Global Projects

​Get Global Projects

​Resource Restrictions

​Allow All Resources

​Specific Resource Types

​Deny Specific Resources

​Wildcard Patterns

​Source Repositories

​Destinations

​Next Steps

Application API

Cluster API

Repository API

Overview

AppProject Resource

AppProject Spec

Example AppProject

API Operations

List Projects

Get Project

Get Detailed Project

Create Project

Update Project

Delete Project

Token Management

Create Project Token

Delete Project Token

RBAC Policies

Policy Components

Policy Examples

Sync Windows

Get Sync Windows

Sync Window Configuration

Events & Monitoring

List Project Events

List Project Links

Global Projects

Get Global Projects

Resource Restrictions

Allow All Resources

Specific Resource Types

Deny Specific Resources

Wildcard Patterns

Source Repositories

Destinations

Next Steps