Skip to main content
API Keys are long-lived credentials for integrations, bots, and backend services. Unlike sessions (for browsers) or JWT tokens (temporary), API keys persist until you revoke them.

​
API Key Format

All API keys follow the same format: 
ak-{access_id}{secret}
  • ak- prefix identifies the string as an API key
  • Access ID — 32 hex characters (UUID without hyphens), serves as the public identifier
  • Secret — appended directly after the access ID, serves as the private credential
Example: 
ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6
   |---------- access id ----------||------ secret ------|
API keys are case-sensitive, long-lived (no expiration unless rotated), and must be stored securely.

​
Quick Start

Include your API key in the X-API-Key header: 
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: $NOORLE_API_KEY"
Alternative headers are also accepted: API-Key or Authorization: ApiKey .... See Using API Keys for code examples in Python, JavaScript, and Go.
Authorization: Bearer is for JWT tokens only, not API keys.

​
When to Use API Keys vs JWT

Use CaseAPI KeyJWT Token
Server-to-server integrationsYesNo
CLI tools and scriptsYesYes (device flow)
Web applicationsNoYes
Long-lived automationYesNo (expires)
Fine-grained user identityNoYes
Use API keys when your service runs unattended and needs persistent access. Use JWT tokens when you need user identity, short-lived sessions, or browser-based auth.

​
How API Keys Are Created

Noorle supports two ways to create API keys: Service Account Keys — The primary method. Create a service account, and an API key is generated automatically. Best for team environments and production services where you need role-based access, audit trails, and key rotation. Direct API Keys — Create API keys directly from account settings. Best for personal development, quick scripts, and testing. Both methods produce the same key format and work identically in API requests. For step-by-step instructions, see Generating API Keys.

​
Scoping and Permissions

API keys are scoped to limit access:
  • Account-wide keys access all resources — use for trusted internal tools
  • Resource-scoped keys access only specific gateways, agents, or resources — recommended for production and third-party integrations
Permission levels: Read (view resources), Execute (run agents and tools), Manage (create and modify), Admin (full control). Always follow the principle of least privilege: grant only the minimum permissions needed.

​
Key Lifecycle

API keys have three states:
  1. Active — Accepts requests, tracked for usage
  2. Inactive — Disabled but can be re-enabled
  3. Revoked — Permanently disabled, returns 401 Unauthorized

​
Security Essentials

  • Never hardcode keys — Use environment variables or secret managers
  • Rotate regularly — Monthly rotation recommended
  • Monitor usage — Track which services use which keys
  • Scope narrowly — Separate keys for separate purposes
If a key is compromised, revoke it immediately — the revocation takes effect instantly. For detailed security guidance, rotation procedures, and monitoring setup, see API Key Security.

​
Next Steps