Skip to main content
API Keys are long-lived credentials for authenticating with the Noorle API. Use them for integrations, automation, and backend services.
Why are API keys managed under Service Accounts? API keys are now organized under Service Accounts so you can group related keys, assign granular permissions per service, and rotate or revoke keys without affecting other integrations. You can still create direct (personal) keys for quick development — but for production workloads, Service Account keys give you better security and auditability.
For a conceptual overview of API keys, see API Keys in Learn.

​
API Key Format

ak-{access_id}{secret}
  • ak- prefix identifies the string as an API key
  • Access ID — 32 hex characters (UUID without hyphens), public identifier
  • Secret — private credential appended directly after the access ID
API keys are shown only once at creation. Store them immediately in a secure location.

​
Generating API Keys

​
Service Account Keys

The primary method. API keys are automatically generated when you create a service account:
  1. Go to Team > Service Accounts
  2. Click Create Service Account
  3. Fill in name, description, role
  4. Click Create
  5. Copy the displayed API key immediately
To create additional keys for the same service account:
  1. Go to Team > Service Accounts > Select account
  2. Click API Keys tab
  3. Click Generate New Key
  4. Copy and store securely
You can have multiple active keys per service account for rotation scenarios.

​
Direct API Keys

For personal development and quick integrations:
  1. Go to Settings > API Keys
  2. Click Create API Key
  3. Set a name, scope, and permissions
  4. Click Create
  5. Copy the displayed API key immediately
Direct keys are tied to your user account rather than a service account.

​
Using API Keys

​
Authentication Header

Include your API key in the X-API-Key header: 
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6"

​
Environment Variable

Store your key in an environment variable: 
export NOORLE_API_KEY="ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6"

curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: $NOORLE_API_KEY"

​
In Application Code

JavaScript: 
const response = await fetch('https://api.noorle.com/v1/agents', {
  headers: {
    'X-API-Key': process.env.NOORLE_API_KEY
  }
});
Python: 
import requests
import os

headers = {
    'X-API-Key': os.environ['NOORLE_API_KEY']
}
response = requests.get('https://api.noorle.com/v1/agents', headers=headers)
Go: 
req, _ := http.NewRequest("GET", "https://api.noorle.com/v1/agents", nil)
req.Header.Add("X-API-Key", apiKey)
client := &http.Client{}
response, _ := client.Do(req)

​
Managing API Keys

​
View All Keys

  1. Go to Team > Service Accounts > Select account
  2. Click API Keys tab
  3. See all active keys with:
    • Last 6 characters (for identification)
    • Creation date
    • Last used date
    • Status (Active/Revoked)

​
Rotate Keys

Replace an active key with a new one:
1

Generate New Key

Click Generate New Key and copy it.
2

Update Applications

Update all applications and scripts to use the new key.
3

Verify New Key Works

Test the new key in your application:
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: {new_key}"
4

Revoke Old Key

In the API Keys tab, click Revoke on the old key.
5

Monitor for Old Key Usage

Check activity logs to ensure no old key usage within 24 hours.

​
Revoke Keys

Instantly disable a key without deleting the service account:
  1. Go to Team > Service Accounts > Select account
  2. Click API Keys tab
  3. Find the key you want to revoke
  4. Click Revoke
  5. Confirm revocation
Revoked keys will return 401 Unauthorized on all API calls. This is immediate.

​
Delete Keys

Permanently remove a key (only possible after revocation):
  1. Revoke the key first
  2. Wait 24 hours (safety period)
  3. Click Delete
  4. Confirm deletion
This is irreversible.

​
API Key Security

​
Storage Best Practices

Do NOT:
  • Hardcode keys in source code
  • Store in version control (git, etc.)
  • Share via email or chat
  • Store in plain text config files
  • Log or expose in error messages
DO:
  • Store in environment variables
  • Use a secret manager (e.g., HashiCorp Vault, 1Password)
  • Encrypt at rest if stored on disk
  • Restrict file permissions (chmod 600)
  • Use .gitignore to exclude credential files

​
Secret Manager Examples

GitHub Secrets: 
env:
  NOORLE_API_KEY: ${{ secrets.NOORLE_API_KEY }}
Environment Variable: 
export NOORLE_API_KEY="ak-..."
HashiCorp Vault: 
vault kv get secret/noorle/api-key
Secret Manager: 
# Retrieve from your secret manager

​
Least Privilege

  • Create separate service accounts for different purposes
  • Assign only required role and resource restrictions
  • Use Viewer role for read-only access
  • Use Developer role for resource creation/modification

​
Monitoring

Enable audit logging to track API key usage:
  1. Go to Team > Service Accounts > Select account
  2. View Activity tab
  3. Monitor for:
    • Unexpected API calls
    • Failed authentication attempts
    • Access from unusual IP addresses or times
    • Unusual data access patterns

​
Troubleshooting

​
”Invalid API Key” Error

Check:
  • Key format is correct (ak- prefix)
  • Key hasn’t been revoked
  • Key hasn’t been deleted
  • No extra whitespace in the header
Test: 
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: ak-{your_key}" \
  -v  # Show headers for debugging

​
“Unauthorized” (401) Error

The key is valid but doesn’t have permission:
  1. Check service account role (Developer or higher needed)
  2. Verify resource isn’t restricted to other accounts
  3. Ensure service account isn’t disabled

​
Key Stops Working After Rotation

Old key was revoked before all applications updated:
  1. Generate a new key
  2. Update remaining applications
  3. Monitor logs for any old key usage
  4. If critical, create new service account as backup

​
Lost API Key

If compromised:
  1. Revoke the key immediately
  2. Generate a new key
  3. Update all applications
  4. Monitor for unauthorized access
If just forgotten:
  1. Generate a new key
  2. Delete the old key after rotation

​
API Key Limits

LimitValue
Keys per service account10
Key lifetimeUnlimited (until rotation)
Key length44 characters
Rotation delayImmediate
Rate limiting1000 req/min per key

​
API Key Permissions

API keys have the same permissions as their associated service account: 
ak-a1b2c3d4e5f6... → Service Account "ci-bot" → Developer role
The key inherits:
  • Developer role permissions
  • Resource restrictions
  • Account access scope

​
Next Steps