API Keys and Automation

Configure project API keys, service accounts, and inbound webhooks for CI/CD pipeline integration.

Overview

GitOpsHQ provides three mechanisms for programmatic access and automation:

Mechanism	Scope	Use Case
Project API Keys	Single project	Project-scoped CI/CD operations
Service Account Tokens	Organization-wide	Cross-project automation, fleet management
Inbound Webhooks	Per-project endpoint	Event-driven image updates and status sync

Each mechanism has different security characteristics, scoping rules, and lifecycle management. Choose the right one based on your automation requirements.

Project API Keys

Project API keys provide project-scoped programmatic access to the GitOpsHQ API. They are the simplest way to integrate a single project's CI/CD pipeline with GitOpsHQ.

Key Format

All project API keys use the prefix gohq_ followed by a random token:

gohq_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8

The gohq_ prefix allows security tools and secret scanners to identify GitOpsHQ keys in code repositories.

Creating a Project API Key

UI Route: Project Settings → IAM → API Keys

Navigate to API Key Management

Open the project, go to Settings, select the IAM section, and click API Keys.

Create New Key

Click Create API Key. Provide:

Field	Description	Required
Name	Descriptive label (e.g., "GitHub Actions Deploy")	Yes
Scopes	Permissions granted to this key	Yes

Copy the Key

The full API key is displayed only once at creation time. Copy it immediately and store it in your CI/CD platform's secret management.

GitOpsHQ stores a hashed version of the key. The original key cannot be retrieved after this dialog is closed. If you lose the key, you must create a new one.

Configure in CI/CD

Use the key in your pipeline's API calls via the Authorization header:

curl -H "Authorization: Bearer gohq_a1b2c3d4..." \
  https://app.gitopshq.io/api/v2/projects/{slug}/releases

Available Scopes

Scope	Permissions Granted
`read`	Read project configuration, releases, deployments, drift status
`write`	Create/update values, create releases, trigger promotions
`admin`	Full administrative access to the project
`image:update`	Trigger image tag updates for specific services

API key access is restricted by a fixed global path allowlist defined in the backend middleware (apiKeyPathAllowed). Only pre-approved API paths accept API key authentication. Requests to paths outside the allowlist are rejected with 403 Forbidden. This is not configurable per key.

Key Rotation

Create a Replacement Key

Create a new API key with the same scopes and configuration as the old one.

Update Consumers

Update all CI/CD pipelines and integrations to use the new key.

Verify

Confirm that all pipelines are functioning with the new key by checking recent API call logs.

Delete the Old Key

Delete the old key from GitOpsHQ. Any requests using the old key will immediately fail.

Service Accounts

Service accounts are organization-scoped machine identities for automation that needs access across multiple projects or to organization-level resources.

When to Use Service Accounts vs. API Keys

Criterion	Project API Key	Service Account Token
Scope	Single project	Organization-wide
Use case	Project-specific CI/CD	Cross-project automation, fleet management
Multiple tokens	No (one key = one token)	Yes (one account, many tokens)
Role-based access	Scope-based	Role-based (viewer, member, admin)
Action patterns	Fixed global path allowlist	Allowed action patterns
Availability	All tiers	Enterprise tier

Creating a Service Account

UI Route: IAM Center → Service Accounts

Navigate to Service Accounts

From the main navigation, go to IAM Center and select Service Accounts.

Create Service Account

Click Create Service Account. Provide:

Field	Description
Name	Descriptive name (e.g., "CI/CD Pipeline Bot")
Description	Purpose and owner of this service account
Role	Base role: `viewer`, `member`, or `admin`

Create a Token

After the service account is created, navigate to its detail page and click Create Token.

Field	Description
Description	Token purpose (e.g., "GitHub Actions Token")
Scopes	Specific scopes to restrict the token
Allowed Actions	Action pattern list (e.g., `projects.*.releases.create`)
Expiration	Token lifetime

The token is displayed once. It uses the prefix ghqs_:

ghqs_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2

Token Features

Multiple Tokens per Account

A single service account can have multiple tokens. This is useful for:

Different CI/CD platforms using the same identity
Token rotation without disrupting all consumers simultaneously
Different scope restrictions for different pipelines

Allowed Action Patterns

Action patterns provide fine-grained control over what operations a token can perform:

Pattern	Meaning
`projects.*.releases.create`	Create releases in any project
`projects.my-project.*`	All operations on a specific project
`clusters.*.commands.sync`	Sync command on any cluster
`org.members.read`	Read organization member list

Patterns use glob syntax: * matches a single segment, ** matches multiple segments.

Token Rotation

Tokens can be rotated independently of the service account:

Create a new token on the same service account
Update the consuming pipeline to use the new token
Delete the old token

The service account's grants and role remain unchanged during token rotation.

Inbound Webhooks

Inbound webhooks allow external systems to trigger actions in GitOpsHQ via HTTP POST requests. GitOpsHQ provides two built-in webhook endpoints.

Image Update Webhook

Endpoint: POST /api/v1/webhooks/image-update

Triggers image tag updates across configured service deployments. See Environment Compare and Bulk Operations for full details.

Quick reference:

BODY='{"repository":"ghcr.io/myorg/api-gateway","tag":"v2.1.0","registry":"ghcr.io","digest":"sha256:abc123..."}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | cut -d' ' -f2)

curl -X POST https://app.gitopshq.io/api/v1/webhooks/image-update \
  -H "Content-Type: application/json" \
  -H "X-GitOpsHQ-Signature: sha256=$SIGNATURE" \
  -H "X-GitOpsHQ-Timestamp: $TIMESTAMP" \
  -d "$BODY"

ArgoCD Webhook

Endpoint: POST /api/v1/webhooks/argocd

Receives sync status events from ArgoCD. Used as a secondary status reporting channel alongside the agent's gRPC connection.

Webhook Security

Both webhook endpoints use HMAC-SHA256 signature verification. The signature is computed over timestamp + "." + body, not just the body alone.

Header	Value
`X-GitOpsHQ-Signature`	`sha256=<HMAC-SHA256(shared_secret, timestamp + "." + raw_request_body)>`
`X-GitOpsHQ-Timestamp`	Unix timestamp of when the request was signed (required)

Both headers are required for verification. The shared secret is configured per-project in Project Settings → Webhooks.

Outbound Webhooks

GitOpsHQ can send notifications to external systems when events occur. Outbound webhooks complement inbound webhooks by closing the feedback loop.

Supported Channels

Channel	Tier	Description
HTTP Endpoint	Free	POST to any URL with JSON payload
Slack	Pro	Rich message to a Slack channel via webhook URL
Discord	Pro	Formatted message to a Discord channel
Microsoft Teams	Pro	Adaptive card to a Teams channel
Email	Pro	Email notification to configured addresses

Configuring Outbound Webhooks

UI Route: Project Settings → Notifications → Webhooks

Add a Channel

Click Add Channel and select the channel type. Provide the endpoint URL or channel configuration.

Select Event Triggers

Choose which events should trigger a notification:

Event Category	Events
Releases	Created, approved, deployed, rolled back, failed
Drift	Detected, resolved, critical
Clusters	Connected, disconnected, command executed
Governance	Violation created, resolved, break-glass activated
Images	Updated via webhook, updated via bulk operation

Field	Description
Timestamp	When the notification was sent
Event	Which event triggered the notification
Status	Success (2xx), failed (4xx/5xx), or timeout
Response	HTTP status code and response body
Retry	Not applicable (single delivery attempt)

Outbound webhook delivery is a single HTTP attempt with no automatic retries.

CI/CD Integration Patterns

Pattern 1: Build → Update → Promote

The most common pattern for automated deployments:

Loading diagram…

CI builds and pushes a new image
CI sends an image update webhook to GitOpsHQ
GitOpsHQ auto-updates dev environment
After verification, an operator promotes to staging (or auto-promotes if configured)
After staging validation, an operator promotes to production (with approval if required)

Pattern 2: GitOps-Only (No Webhooks)

For teams that prefer full Git-driven workflows:

CI builds and pushes a new image
Developer updates the image tag in GitOpsHQ UI or via API
Changes flow through the standard release → promote workflow

Pattern 3: Service Account for Fleet Operations

For platform teams managing many projects:

# List accessible projects
curl -H "Authorization: Bearer ghqs_..." \
  https://app.gitopshq.io/api/v2/projects

# List releases for one project and filter pending in your automation logic
curl -H "Authorization: Bearer ghqs_..." \
  https://app.gitopshq.io/api/v2/projects/{slug}/releases

# Create a release
curl -X POST -H "Authorization: Bearer ghqs_..." \
  -H "Content-Type: application/json" \
  -d '{"environment":"staging","tenantId":"tenant_01H5K...","title":"staging rollout"}' \
  https://app.gitopshq.io/api/v2/projects/{slug}/releases

# Deploy a release
curl -X POST -H "Authorization: Bearer ghqs_..." \
  https://app.gitopshq.io/api/v2/releases/{id}/deploy

Security Best Practices

Practice	Description
Rotate keys every 90 days	Set a calendar reminder and enforce rotation through organizational policy.
Use minimum required scopes	A CI pipeline that only updates images should only have `image:update` scope.
Prefer service accounts over personal tokens	Service accounts are auditable machine identities; personal tokens are tied to individual users who may leave the organization.
Store secrets in CI/CD secret management	Never hardcode API keys or webhook secrets in pipeline definitions. Use GitHub Actions secrets, GitLab CI variables, Jenkins credentials store, etc.
Monitor via audit logs	Regularly review API key usage in the audit log. Investigate unexpected patterns.
Disable unused keys immediately	When a pipeline is decommissioned, delete its API key the same day.
Use separate keys per pipeline	Each CI/CD pipeline should have its own API key. Never share keys across pipelines.

Secret Scanner Integration

GitOpsHQ key prefixes (gohq_ and ghqs_) are registered with common secret scanning tools:

Tool	Support
GitHub Secret Scanning	Auto-detects `gohq_` and `ghqs_` prefixes
GitLab Secret Detection	Pattern matching for GitOpsHQ key formats
truffleHog	Custom regex for `gohq_` and `ghqs_` patterns
gitleaks	Built-in rule for GitOpsHQ keys

If a secret scanner detects a GitOpsHQ key in a public repository, rotate the key immediately. The exposed key should be considered compromised.

API Authentication Reference

All authenticated API requests use Bearer token authentication:

Authorization: Bearer <token>

Where <token> is either:

A project API key (gohq_...)
A service account token (ghqs_...)
A user session token (for interactive API usage)

Error Responses

Status	Meaning	Action
`401 Unauthorized`	Missing or invalid token	Check the token is correct
`403 Forbidden`	Token is valid but lacks required scope or path access	Review the token's scopes
`429 Too Many Requests`	Rate limit exceeded	Back off and retry with exponential delay

Core Architecture — Understand the overall system design
Environment Compare and Bulk Operations — Webhook-driven bulk image updates
Dashboard — Monitor API key usage in audit entries
Glossary — Definitions of API key and service account terms

On this page