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

sourceRepos

string[]

required

Allowed source repositories (supports wildcards)

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

destinations

ApplicationDestination[]

required

Allowed deployment destinations

Show ApplicationDestination fields

server

string

Kubernetes server URL (supports wildcards)

name

string

Cluster name (alternative to server)

namespace

string

Target namespace (supports wildcards)

clusterResourceWhitelist

ResourceSelector[]

Allowed cluster-scoped resources

Show ResourceSelector fields

group

string

API group (empty for core)

kind

string

Resource kind

clusterResourceBlacklist

ResourceSelector[]

Denied cluster-scoped resources

namespaceResourceWhitelist

ResourceSelector[]

Allowed namespace-scoped resources

namespaceResourceBlacklist

ResourceSelector[]

Denied namespace-scoped resources

roles

ProjectRole[]

RBAC roles for the project

Show ProjectRole fields

name

string

required

Role name

description

string

Role description

policies

string[]

required

RBAC policies (Casbin format)

groups

string[]

SSO groups bound to this role

jwtTokens

JWTToken[]

JWT tokens for automation

syncWindows

SyncWindow[]

Time windows for controlling sync operations

sourceNamespaces

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"

Get Project

Retrieve a specific project.

GET /api/v1/projects/{name}

name

string

required

Project name

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

Get Detailed Project

Get project with global projects and scoped resources.

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

name

string

required

Project name

Response includes:

Project definition
Global projects
Scoped repositories
Scoped clusters

Create Project

Create a new project.

POST /api/v1/projects

project

AppProject

required

Complete AppProject resource

upsert

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"}
        ]
      }
    }
  }'

Update Project

Update an existing project.

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

project

AppProject

required

Updated AppProject resource

Delete Project

Delete a project.

DELETE /api/v1/projects/{name}

name

string

required

Project name

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

Token Management

Create Project Token

Generate a JWT token for a project role.

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

project

string

required

Project name

role

string

required

Role name

description

string

Token description

expiresIn

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
  }'

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

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

name

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

name

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

name

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

Resources

gRPC Services

​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

Build docs developers (and LLMs) love

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