API Authentication

DgiDgi One uses a secure, token-based authentication system. All API requests must be authenticated using an API Key or a JWT Token.

API Keys (Recommended)

API Keys are the primary method for authenticating server-side applications, scripts, CI/CD pipelines, and SDKs. They are long-lived, opaque tokens that map to specific permissions and scopes.

Key Format

DgiDgi One API keys use a distinct prefix to help you identify their purpose and prevent accidental check-ins to source control.

Prefix	Type	Description
chy_sdk_	SDK Key	Standard key for application backends and SDK integration.
chy_cli_	CLI Key	Used by the DgiDgi One Command Line Interface.
chy_ci_	CI/CD Key	For automated deployment pipelines (GitHub Actions, GitLab CI).
chy_int_	Integration Key	For third-party integrations (Zapier, Slack, etc.).
chy_mkt_	Marketplace Key	Specialized keys for marketplace interactions.

Generating API Keys

1. Navigate to Settings > Security > API Keys in the DgiDgi One dashboard.
2. Click Create Key.
3. Enter a name (e.g., "Production Backend") and select the Key Type.
4. Choose the Environment (Development, Staging, or Production).
5. (Optional) Configure specific Scopes to limit what this key can do.
6. Click Create.
7. Copy the key immediately. For security reasons, the full key is only shown once. We only store a cryptographic hash of the key.

Using API Keys

Pass the API key in the Authorization header of your HTTP requests:

Authorization: Bearer chy_sdk_...

Example with curl:

curl https://api.dgidgi.ai/api/v1/projects \
  -H "Authorization: Bearer chy_sdk_a1b2c3d4e5..."

Example with Node.js SDK:

import { DgiDgi One } from '@dgidgi/sdk';

const client = new DgiDgi One({
  apiKey: 'chy_sdk_a1b2c3d4e5...',
});

JWT Tokens (Internal)

JSON Web Tokens (JWTs) are short-lived tokens used primarily by the DgiDgi One frontend and for temporary sessions.

• Minting: When you use an API Key, the system validates it and internally "mints" a short-lived JWT to handle the request session.
• Usage: You generally do not need to manage JWTs manually unless you are building a custom frontend client that acts on behalf of a user.

Scopes

API keys and tokens can be scoped to limit their permissions. Common scopes include:

Scope	Description
projects:read	Read project data
projects:write	Create, update, delete projects
billing:read	View billing summary and invoices
billing:write	Purchase credits, manage subscriptions, redeem gift cards
secrets:read	List and view secret metadata
secrets:write	Create, update, delete secrets
agents:read	View agent configurations
agents:write	Create, configure, run agents

Billing Scope Requirements

The following billing endpoints require billing:write scope:

• POST /billing/gift-cards/redeem - Redeem gift codes
• POST /billing/credits/purchase - Purchase credits
• POST /billing/subscription/create - Create subscriptions
• POST /billing/portal - Access billing portal

Read-only endpoints (/billing/summary, /billing/invoices) only require authentication.

Security Best Practices

• Least Privilege: Always scope your API keys. If a key only needs to read projects, do not give it projects:write permissions.
• Environment Isolation: Use separate keys for Development, Staging, and Production.
• Rotation: regularly rotate your keys. If you suspect a key has been compromised, revoke it immediately from the dashboard.
• IP Allowlist: Configure the IP Allowlist in Settings > Security > Network Security to restrict usage of your keys to known IP addresses (e.g., your office VPN or server IPs).

Error Codes

Status	Code	Description
401	UNAUTHORIZED	The API key is missing, invalid, or expired.
403	FORBIDDEN	The API key is valid but lacks the required scope/permission for the action.