Authentication

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

Sign in to SpecStory Cloud
Navigate to Settings → API Keys
Generate a new API key for your application
Copy the generated token securely

Warning

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

const response = await fetch('https://cloud.specstory.com/api/v1/projects', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://cloud.specstory.com/api/v1/projects',
    headers=headers
)

data = response.json()

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://cloud.specstory.com/api/v1/projects", nil)
    
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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

// Using process.env
const apiKey = process.env.SPECSTORY_API_KEY;

const response = await fetch('https://cloud.specstory.com/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

import os
import requests

api_key = os.getenv('SPECSTORY_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://cloud.specstory.com/api/v1/projects',
    headers=headers
)

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:

Sign in to SpecStory Cloud
Navigate to Settings → API Keys
Find the key you want to revoke
Click the "Revoke" button
Confirm the revocation

Warning

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.