Cognigate › Docs › Authentication

Documentation

Authentication

API key management, authentication flows, and security best practices.

Overview

All Cognigate API requests require authentication via API key. Keys are scoped to an organization and carry specific permissions.

API Key Authentication

Include your API key in the Authorization header:

curl -X POST https://cognigate.dev/v1/intents \
  -H "Authorization: Bearer cg_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"my-agent","action":"read","resource":"documents/*"}'

Key Prefixes

PrefixEnvironmentDescription
cg_live_ProductionFull access, rate limits apply per tier
cg_test_TestingSandbox only, no production side effects
cg_dev_DevelopmentLocal development, relaxed rate limits

Generating API Keys

API keys can be generated through the admin API:

# Generate a new API key
curl -X POST https://cognigate.dev/v1/auth/keys \
  -H "Authorization: Bearer cg_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service-key",
    "scopes": ["intents:write", "trust:read", "proofs:read"],
    "expiresIn": "90d"
  }'

Key Scopes

ScopePermits
agents:readList and retrieve agent details
agents:writeRegister and update agents
intents:writeSubmit governance intents
trust:readQuery trust scores and history
trust:writeSubmit trust signals
proofs:readRetrieve proof receipts and chains
admin:*Full administrative access

Error Responses

CodeHTTP StatusDescription
E1001401API key is missing from the Authorization header
E1002401API key is invalid or has been revoked
E1003401API key has expired — generate a new one
E1004403Insufficient permissions for this operation
Security Note: Never expose API keys in client-side code, public repositories, or logs. Use environment variables and rotate keys regularly. All keys can be revoked immediately via the admin API.

SDK Authentication

import { Vorion } from '@vorionsys/sdk';

const vorion = new Vorion({
  apiEndpoint: 'https://cognigate.dev',
  apiKey: process.env.COGNIGATE_API_KEY,
});

Next Steps