Skip to content

Authentication#

The Storyteller CMS API uses API key authentication to secure access to content management endpoints.

Prerequisite

Before you can authenticate with the CMS API, you must have received approval from the Storyteller team and been granted access to create server applications in the CMS.

API Key Generation#

To access the CMS API, you'll need to generate an API key through the Storyteller CMS:

  1. Log into the Storyteller CMS with your approved account
  2. Navigate to Server Apps in the administration section
  3. Create a New Server App - This will generate your unique API key
  4. Copy and Store your API key securely

Security

Your API key provides full access to CMS operations. Keep it secure and never share it publicly or commit it to version control.

Using Your API Key#

Once you have your API key, you can authenticate requests to the CMS API using either of these methods:

Include your API key in the x-storyteller-api-key header:

GET /api/cms/stories
Host: api.storyteller.example.com
x-storyteller-api-key: your-api-key-here

Method 2: Query String Parameter#

Alternatively, you can pass the API key as a query string parameter:

GET /api/cms/stories?x-storyteller-api-key=your-api-key-here
Host: api.storyteller.example.com

Code Examples#

// Using fetch with header
fetch('https://api.storyteller.example.com/api/cms/stories', {
  headers: {
    'x-storyteller-api-key': 'your-api-key-here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

// Using query parameter
fetch('https://api.storyteller.example.com/api/cms/stories?x-storyteller-api-key=your-api-key-here')
.then(response => response.json())
.then(data => console.log(data));

import requests

# Using header
headers = {'x-storyteller-api-key': 'your-api-key-here'}
response = requests.get('https://api.storyteller.example.com/api/cms/stories', headers=headers)

# Using query parameter
params = {'x-storyteller-api-key': 'your-api-key-here'}
response = requests.get('https://api.storyteller.example.com/api/cms/stories', params=params)

using HttpClient client = new HttpClient();

// Using header
client.DefaultRequestHeaders.Add("x-storyteller-api-key", "your-api-key-here");
var response = await client.GetAsync("https://api.storyteller.example.com/api/cms/stories");
var content = await response.Content.ReadAsStringAsync();

// Using query parameter
var urlWithParam = "https://api.storyteller.example.com/api/cms/stories?x-storyteller-api-key=your-api-key-here";
var responseWithParam = await client.GetAsync(urlWithParam);
var contentWithParam = await responseWithParam.Content.ReadAsStringAsync();

# Using header (recommended)
curl -H "x-storyteller-api-key: your-api-key-here" \
     https://api.storyteller.example.com/api/cms/stories

# Using query parameter
curl "https://api.storyteller.example.com/api/cms/stories?x-storyteller-api-key=your-api-key-here"

Authentication Errors#

If authentication fails, you'll receive an HTTP 401 Unauthorized response:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Common causes of authentication failures:

  • Missing API key - No x-storyteller-api-key header or query parameter provided
  • Invalid API key - The provided key is incorrect or has been revoked
  • Expired access - Your server app access may have been suspended

If you encounter authentication issues, please contact the Storyteller team for assistance.