Skip to content
docs
Menu
#

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.

On this page
#

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
#

Making Authenticated Requests

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

bash

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

Request Headers

http

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

Authentication Examples

cURL

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

JavaScript

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();

Python

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()

Go

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:

Bash

export SPECSTORY_API_KEY="your_api_key_here"

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

Node.js

// 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'
  }
});

Python

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:

json

{
  "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:

json

{
  "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

Secure Storage
  • 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)
Key Rotation
  • 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
Access Control
  • 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
#

Testing Authentication

You can test your authentication setup with a simple request to list your projects:

bash

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

A successful response indicates your authentication is working correctly:

json

{
  "success": true,
  "data": {
    "projects": [...],
    "total": 5
  }
}
#

GraphQL Authentication

GraphQL requests use the same Bearer token authentication:

bash

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.