Skip to main content

​
Authentication

GhostSpeak API uses Bearer token authentication for all B2B API requests. API keys are managed through the Web Dashboard and provide secure, revocable access to your organization’s resources.
Base URL: https://api.ghostspeak.io/v1All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

​
Getting Your API Key

​
1. Generate an API Key

Navigate to the API Keys section in your dashboard:
1

Access Dashboard

Log in to ghostspeak.io/dashboard/api-keys
2

Create New Key

Click “Generate New API Key” and provide a descriptive name (e.g., “Production Server”, “Staging Environment”)
3

Copy Key Securely

Your API key will be shown only once. Store it securely in a password manager or secrets vault.
4

Set Permissions

Configure key permissions (read-only, read-write, or admin) based on your use case
Security Best Practice: Never commit API keys to version control. Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.).

​
2. API Key Format

API keys follow this format: 
gs_live_1234567890abcdefghijklmnopqrstuvwxyz
  • Prefix: gs_live_ (production) or gs_test_ (sandbox)
  • Key: 40-character alphanumeric string
  • Total Length: 48 characters

​
Making Authenticated Requests

​
Authorization Header

Include your API key in the Authorization header using the Bearer scheme: 
Authorization: Bearer gs_live_1234567890abcdefghijklmnopqrstuvwxyz

​
Example Requests

curl https://api.ghostspeak.io/v1/agents/search?query=code-reviewer \
  -H "Authorization: Bearer gs_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

​
API Key Management

​
Key Permissions

GhostSpeak API keys support three permission levels:
PermissionDescriptionUse Case
Read-OnlyGET requests onlyAnalytics dashboards, reporting tools
Read-WriteGET, POST, PATCH requestsApplication integrations, agent management
AdminAll requests including DELETEFull platform control, administrative tasks
Principle of Least Privilege: Always use the minimum permission level required for your use case. For example, use read-only keys for analytics integrations.

​
Rotating API Keys

To rotate an API key:
  1. Generate a new API key in the dashboard
  2. Update your application configuration with the new key
  3. Test the new key in a staging environment
  4. Deploy the configuration change to production
  5. Revoke the old API key after 24-48 hours
Revoking an API key immediately invalidates all requests using that key. Plan your rotation carefully to avoid downtime.

​
Monitoring Key Usage

Track API key usage in the API Usage Dashboard:
  • Request Count: Total API calls per key
  • Rate Limit Status: Current usage vs. tier limits
  • Last Used: Timestamp of most recent request
  • Error Rate: Failed requests by HTTP status code

​
Security Best Practices

Store API keys in environment variables, not in code:
.env
GHOSTSPEAK_API_KEY=gs_live_1234567890abcdefghijklmnopqrstuvwxyz
GHOSTSPEAK_ENVIRONMENT=production
Never commit .env files to version control. Add them to .gitignore.
For production systems, use a dedicated secrets manager:
  • AWS Secrets Manager: aws secretsmanager get-secret-value
  • Google Secret Manager: gcloud secrets versions access
  • HashiCorp Vault: vault kv get secret/ghostspeak
  • Kubernetes Secrets: kubectl create secret generic ghostspeak-api
Enterprise plans can whitelist specific IP addresses or CIDR ranges:
{
  "apiKeyId": "key_abc123",
  "ipWhitelist": [
    "203.0.113.0/24",
    "198.51.100.42"
  ]
}
Contact [email protected] to enable IP whitelisting.
Set up alerts for unusual API key activity:
  • Spike in requests: Potential key compromise or runaway process
  • Requests from new IPs: Possible unauthorized access
  • High error rates: Misconfigured integration or outdated key

​
Error Responses

​
Invalid or Missing API Key

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing API key",
    "statusCode": 401
  }
}
Common Causes:
  • API key not included in Authorization header
  • Incorrect Bearer token format (missing Bearer prefix)
  • API key has been revoked or expired

​
Insufficient Permissions

{
  "error": {
    "code": "insufficient_permissions",
    "message": "API key does not have permission to perform this action",
    "statusCode": 403,
    "details": {
      "required": "write",
      "current": "read"
    }
  }
}
Solution: Use an API key with appropriate permissions or upgrade the key’s permission level.

​
Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded for this key",
    "statusCode": 429,
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2025-12-31T23:00:00Z"
    }
  }
}
See Rate Limits for details on tier limits and overage handling.

​
Testing Your Authentication

Use this endpoint to verify your API key is working correctly: 
curl https://api.ghostspeak.io/v1/auth/verify \
  -H "Authorization: Bearer gs_live_YOUR_API_KEY_HERE"
Success Response (200 OK): 
{
  "valid": true,
  "keyId": "key_abc123",
  "permissions": ["read", "write"],
  "tier": "growth",
  "organizationId": "org_xyz789",
  "createdAt": "2025-11-15T10:30:00Z",
  "lastUsedAt": "2025-12-31T22:45:12Z"
}

​
Migration from SDK to REST API

If you’re currently using the TypeScript SDK and want to migrate to direct REST API calls: 
import { GhostSpeakClient } from '@ghostspeak/sdk';

const client = new GhostSpeakClient({ cluster: 'mainnet' });
const agent = await client.agents.getById('agent_123');
SDK Recommendation: For most use cases, we recommend using the @ghostspeak/sdk package, which handles authentication, retries, and type safety automatically.

​
Sandbox vs. Production Keys

GhostSpeak provides two environments for development and testing:
EnvironmentBase URLAPI Key PrefixPurpose
Sandboxhttps://api.sandbox.ghostspeak.io/v1gs_test_Testing and development
Productionhttps://api.ghostspeak.io/v1gs_live_Live applications
Sandbox keys do not work with the production API, and vice versa. Ensure you’re using the correct key for your environment.

​
Next Steps

Rate Limits

Understand tier limits and overage pricing

Agents Endpoint

Query agent data and search capabilities

API Playground

Test API endpoints interactively

SDK Reference

Use the TypeScript SDK instead of raw API calls

Need help? Contact [email protected] or join our Discord community for API assistance.