Skip to main content
The SpecStory Cloud API uses JWT Bearer token authentication for all requests. You’ll need to include your API key in the Authorization header of every request.

​
Getting Your API Key

  1. Sign in to SpecStory Cloud
  2. Navigate to Settings → API Keys
  3. Generate a new API key for your application
  4. Copy the generated token securely
Keep your API key secure! Your API key provides full access to your SpecStory data. Never commit it to version control or share it publicly.

​
Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cloud.specstory.com/api/v1/projects

​
Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

​
Authentication Examples

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.specstory.com/api/v1/projects

​
Environment Variables

For security and convenience, store your API key as an environment variable: 
export SPECSTORY_API_KEY="your_api_key_here"

curl -H "Authorization: Bearer $SPECSTORY_API_KEY" \
  https://cloud.specstory.com/api/v1/projects

​
Authentication Errors

The API returns specific error codes for authentication issues:

​
401 Unauthorized

Returned when no authentication token is provided or the token is invalid: 
{
  "success": false,
  "error": "Invalid session token"
}
Common causes:
  • Missing Authorization header
  • Invalid or expired API key
  • Malformed Bearer token format

​
403 Forbidden

Returned when the authenticated user doesn’t have permission for the requested resource: 
{
  "success": false,
  "error": "Insufficient permissions"
}
Common causes:
  • Attempting to access another user’s projects or sessions
  • API key doesn’t have required permissions

​
API Key Management

​
Best Practices

  • Store API keys in environment variables or secure credential stores
  • Never commit API keys to version control
  • Use different API keys for different environments (development, staging, production)
  • Rotate API keys regularly (recommended: every 90 days)
  • Generate new keys before revoking old ones to avoid service interruption
  • Monitor API key usage in the SpecStory Cloud dashboard
  • Use separate API keys for different applications or services
  • Revoke unused or compromised keys immediately
  • Monitor API usage patterns for unusual activity

​
Revoking API Keys

To revoke an API key:
  1. Sign in to SpecStory Cloud
  2. Navigate to Settings → API Keys
  3. Find the key you want to revoke
  4. Click the “Revoke” button
  5. Confirm the revocation
Revoking an API key immediately invalidates it. Any applications using the revoked key will start receiving 401 authentication errors.

​
Testing Authentication

You can test your authentication setup with a simple request to list your projects: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cloud.specstory.com/api/v1/projects
A successful response indicates your authentication is working correctly: 
{
  "success": true,
  "data": {
    "projects": [...],
    "total": 5
  }
}

​
GraphQL Authentication

GraphQL requests use the same Bearer token authentication: 
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { id name } }"}' \
  https://cloud.specstory.com/api/v1/graphql
The interactive GraphQL playground at https://cloud.specstory.com/api/v1/graphql also supports authentication - just add your Bearer token in the headers section.