Gnosari Documentation

Appearance

API Keys ​

Generate and manage API keys for secure authentication with Gnosari's API.

Overview ​

API keys allow you to authenticate programmatic requests to your Gnosari account. Use them to integrate Gnosari agents and teams into your applications, automation workflows, or custom tools.

Security Note: API keys are like passwords. Never share them publicly, commit them to version control, or expose them in client-side code.

Accessing the API Keys Page ​

  1. Click your profile picture in the top-right corner
  2. Select Settings from the dropdown
  3. Navigate to API Keys in the settings sidebar

Or go directly to: /settings/api-keys

Creating an API Key ​

Generate a new API key for your account.

Step-by-Step ​

  1. Navigate to Settings → API Keys
  2. Click the Create API Key button (top-right)
  3. Enter a descriptive name for the key
  4. (Optional) Select a status (defaults to Active)
  5. Click Create

API Key Name Best Practices ​

Use descriptive names that indicate:

  • Purpose: "Production Bot", "Staging Environment", "Development Testing"
  • Application: "Mobile App Integration", "Zapier Workflow"
  • Location: "AWS Lambda Function", "Heroku Backend"

Examples:

  • ✅ "Production Mobile App v2"
  • ✅ "Staging CI/CD Pipeline"
  • ✅ "Development - Local Testing"
  • ❌ "Key 1"
  • ❌ "Test"

API Key Value - Critical Information ​

This is the ONLY time you'll see the actual API key value.

After Creating ​

The API key value appears in the success dialog immediately after creation.

What You See:

gsk_1234567890abcdef...

Critical Actions:

  1. Copy the key immediately using the copy button
  2. Store it securely in your password manager or environment variables
  3. Do not close the dialog until you've copied the key

Security Warning ​

Once you close the creation dialog, the key value is hidden forever. You cannot retrieve it again.

If you lose the key:

  • You must delete the old key
  • Create a new key
  • Update your applications with the new key

API Key Statuses ​

Each API key has a status that controls its behavior.

StatusBehaviorUse Case
Active✅ Accepts API requestsProduction use, active integrations
Inactive❌ Rejects API requestsTemporary disable without deleting
Revoked❌ Permanently disabledSecurity incident, key compromised

Status Transitions ​

Active → Inactive:

  • Temporarily disable a key
  • Can be reactivated later

Active/Inactive → Revoked:

  • Permanent action (cannot be undone)
  • Use when key is compromised

Managing API Keys ​

View and manage all your API keys in one place.

API Key List ​

Each key displays:

  • Name: Descriptive name you provided
  • Status Badge: Visual indicator (Active, Inactive, Revoked)
  • Created Date: When the key was generated
  • Last Modified: When status was last changed

Key Management Actions ​

Edit Key:

  1. Click the key card
  2. Click the Edit icon (pencil)
  3. Update the name or status
  4. Click Save

Delete Key:

  1. Click the key card
  2. Click the Delete icon (trash can)
  3. Confirm deletion in the modal
  4. Key is permanently removed

Warning: Deleting an API key is permanent and cannot be undone. Any applications using this key will immediately stop working.

Using API Keys ​

Authenticate your API requests with your API key.

Authentication Header ​

Include your API key in the X-API-Key header:

bash
curl -X GET "https://api.gnosari.com/api/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY"

Store API keys in environment variables, never in code.

Example (.env file):

bash
GNOSARI_API_KEY=gsk_1234567890abcdef...

Example (Node.js):

javascript
const apiKey = process.env.GNOSARI_API_KEY

const response = await fetch('https://api.gnosari.com/api/v1/agents', {
  headers: {
    'X-API-Key': apiKey
  }
})

Example (Python):

python
import os
import requests

api_key = os.environ.get('GNOSARI_API_KEY')

response = requests.get(
    'https://api.gnosari.com/api/v1/agents',
    headers={'X-API-Key': api_key}
)

Never Hardcode API Keys ​

❌ WRONG - Hardcoded in Code:

javascript
// DON'T DO THIS
const apiKey = 'gsk_1234567890abcdef...'

✅ CORRECT - Environment Variable:

javascript
// DO THIS
const apiKey = process.env.GNOSARI_API_KEY

Security Best Practices ​

Storage ​

Do:

  • ✅ Store in environment variables
  • ✅ Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
  • ✅ Keep in password managers for backup

Don't:

  • ❌ Commit to git repositories
  • ❌ Share via email or chat
  • ❌ Hardcode in application code
  • ❌ Expose in client-side JavaScript

Rotation ​

When to Rotate (Create New + Delete Old):

  • Every 90 days (recommended)
  • When team member with key access leaves
  • After security incident
  • If key may have been exposed

How to Rotate:

  1. Create a new API key
  2. Update your applications to use the new key
  3. Test that the new key works
  4. Delete the old key

Revocation ​

Revoke Immediately If:

  • Key appears in public repository
  • Key shared accidentally
  • Suspicious API activity detected
  • Team member with access leaves suddenly

API Key Limits ​

Maximum Keys per Account:

  • Free plan: 5 API keys
  • Professional plan: 25 API keys
  • Enterprise plan: Unlimited API keys

Rate Limits: API requests are subject to your subscription plan limits. See Subscription Management for details.

Troubleshooting ​

"Invalid API Key" Error ​

Possible Causes:

  • Key status is Inactive or Revoked
  • Key was deleted
  • Typo in the key value
  • Wrong environment (using staging key in production)

Solutions:

  1. Check key status in Settings → API Keys
  2. Verify the entire key value was copied correctly
  3. Generate a new key if old one was deleted

"Rate Limit Exceeded" Error ​

Cause: You've exceeded your plan's API call limit.

Solutions:

  • Wait until your billing period resets
  • Upgrade to a higher plan
  • Optimize your API usage

Key Not Working After Creation ​

Possible Causes:

  • Key status set to Inactive
  • Not using the correct authentication header

Solutions:

  1. Verify key status is Active
  2. Check you're using X-API-Key header (not Authorization)
  3. Ensure no extra spaces or characters in key value

API Key Best Practices Summary ​

  1. Name keys descriptively - Know what each key is for
  2. Copy immediately - You only see the value once
  3. Store securely - Environment variables, not code
  4. Rotate regularly - Every 90 days minimum
  5. Delete unused keys - Reduce security surface area
  6. Use different keys per environment - Separate dev, staging, production
  7. Monitor usage - Watch for unexpected API activity
  8. Revoke on compromise - Act immediately if exposed

Next Steps ​

Last updated: 2026-02-15