ghost-admin-api-auth

Ghost Admin API Authentication

Overview

The Ghost Admin API has three authentication methods. Choose based on your use case:

Method	Use When
Integration Token (JWT)	Server-side automations, CI/CD, scripts — no user context needed
Staff Access Token	Respecting a specific user's role/permissions
User Session (cookie)	Browser-based admin clients, interactive tools requiring 2FA support

Base URL: https://{admin_domain}/ghost/api/admin/

Always include the API version header on every request:

Accept-Version: v5.0

---

Method 1: Integration Token (JWT) — Recommended for Scripts

Step 1 — Create an integration and get your key

In Ghost Admin: Settings → Advanced → Integrations → Add custom integration.

Copy the Admin API Key. It has the form:

{id}:{secret}

Example: 64f2f3e5a1b2c3d4e5f6a7b8:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

Step 2 — Generate a JWT

The JWT must be:

• Algorithm: HS256
• Audience (aud): /admin/
• Issued-at (iat): current Unix timestamp
• Expiry (exp): max 5 minutes from now
• Key ID (kid): the {id} portion of the Admin API Key

Node.js example:

import jwt from 'jsonwebtoken';

function ghostAdminToken(adminApiKey) {
  const [id, secret] = adminApiKey.split(':');
  return jwt.sign({}, Buffer.from(secret, 'hex'), {
    keyid: id,
    algorithm: 'HS256',
    expiresIn: '5m',
    audience: '/admin/',
  });
}

Python example:

import jwt, time, binascii

def ghost_admin_token(admin_api_key: str) -> str:
    id_, secret = admin_api_key.split(':')
    iat = int(time.time())
    payload = {'iat': iat, 'exp': iat + 300, 'aud': '/admin/'}
    return jwt.encode(payload, bytes.fromhex(secret), algorithm='HS256',
                      headers={'kid': id_})

Step 3 — Make requests

TOKEN=$(node -e "
const jwt = require('jsonwebtoken');
const key = process.env.GHOST_ADMIN_API_KEY;
const [id, secret] = key.split(':');
console.log(jwt.sign({}, Buffer.from(secret,'hex'), {
  keyid: id, algorithm: 'HS256', expiresIn: '5m', audience: '/admin/'
}));
")

curl -H "Authorization: Ghost $TOKEN" \
     -H "Accept-Version: v5.0" \
     https://example.com/ghost/api/admin/posts/

Key rules:

• Tokens expire in 5 minutes — generate fresh per request or per batch
• Never reuse tokens across sessions
• Store the Admin API Key in an environment variable, never in code

---

Method 2: Staff Access Token

Step 1 — Get the token

In Ghost Admin: User profile → bottom of page → Staff access token → Copy.

This token is tied to that staff user's role and respects their permissions.

Step 2 — Make requests

curl -H "Authorization: Ghost $STAFF_ACCESS_TOKEN" \
     -H "Accept-Version: v5.0" \
     https://example.com/ghost/api/admin/posts/

When to use: When you want operations scoped to a specific user's role (e.g., an Author token cannot publish, a Contributor token cannot create tags).

---

Method 3: User Session (Cookie)

Step 1 — Authenticate

curl -c cookies.txt -X POST \
     -H "Content-Type: application/json" \
     -H "Accept-Version: v5.0" \
     -d '{"username":"[email protected]","password":"yourpassword"}' \
     https://example.com/ghost/api/admin/session/

Step 2 — Use the session

curl -b cookies.txt \
     -H "Accept-Version: v5.0" \
     -H "X-CSRF-Token: $(grep ghost-csrf cookies.txt | awk '{print $NF}')" \
     https://example.com/ghost/api/admin/posts/

Notes:

• Requires CSRF token on state-mutating requests (POST, PUT, DELETE)
• Supports 2FA — if enabled, a second request is required after initial auth
• Not recommended for automated scripts; use JWT instead

---

Roles & Permissions Reference

Role	Capabilities
Contributor	Write posts only; cannot publish
Author	Create and publish posts and tags
Editor	Manage authors/contributors; edit their content
Administrator	Full access to all settings and data
Owner	Administrator + billing; permanent, cannot be removed

---

Environment Variable Convention

Store credentials as:

GHOST_ADMIN_URL=https://example.com
GHOST_ADMIN_API_KEY=64f2f3e5a1b2c3d4e5f6a7b8:a1b2c3d4...

All other Ghost Admin API skills expect these variables to be set.

---

Checklist

• Integration created in Ghost Admin (Settings → Advanced → Integrations)
• Admin API Key stored in GHOST_ADMIN_API_KEY env var
• Ghost URL stored in GHOST_ADMIN_URL env var
• JWT generated fresh per request (not cached beyond 5 minutes)
• Accept-Version: v5.0 header included on all requests
• Authorization: Ghost {token} header format confirmed (not Bearer)