Ghost User Management API Guide

Auth method: JWT (Admin API Key) - a key ID and secret are combined to sign a short-lived JWT Bearer token; no OAuth 2.0 flow.

Setup steps

1. In Ghost Admin, navigate to Settings → Integrations → Add custom integration.
2. Copy the Admin API Key (format: {key_id}:{secret}).
3. Split the key on : to obtain key_id and secret.
4. Sign a JWT: header {alg:'HS256',typ:'JWT',kid:key_id}, payload {iat:<now_unix>,exp:<now+5min>,aud:'/admin/'}, signed with Buffer.from(secret,'hex') using HMAC-SHA256.
5. Send requests with header Authorization: Ghost <jwt_token>.

Required scopes

List staff users

• Method: GET
• URL: https://{site}/ghost/api/admin/users/?limit=all&include=roles
• Watch out for: Default limit is 15. Use limit=all to retrieve all users in one request. Does NOT return Members (subscribers), only staff.

Request example

GET /ghost/api/admin/users/?limit=all&include=roles
Authorization: Ghost <jwt>

Response example

{
  "users": [
    {"id":"1","name":"Jane","email":"jane@example.com",
     "status":"active","roles":[{"name":"Administrator"}]}
  ],
  "meta":{"pagination":{"page":1,"limit":"all","total":1}}
}

Read single staff user by ID

• Method: GET
• URL: https://{site}/ghost/api/admin/users/{id}/?include=roles
• Watch out for: Response is always wrapped in a users array even for single-resource reads.

Request example

GET /ghost/api/admin/users/6123abc/?include=roles
Authorization: Ghost <jwt>

Response example

{
  "users": [
    {"id":"6123abc","name":"Jane","email":"jane@example.com",
     "status":"active","roles":[{"name":"Editor"}]}
  ]
}

Read current authenticated user (me)

• Method: GET
• URL: https://{site}/ghost/api/admin/users/me/?include=roles
• Watch out for: Admin API keys are associated with an integration pseudo-user, not a real staff account. me returns that integration user.

Request example

GET /ghost/api/admin/users/me/
Authorization: Ghost <jwt>

Response example

{
  "users": [
    {"id":"6123abc","name":"API Integration",
     "roles":[{"name":"Administrator"}]}
  ]
}

Update staff user

• Method: PUT
• URL: https://{site}/ghost/api/admin/users/{id}/
• Watch out for: Request body must wrap the user object in a users array. Must include id inside the body object. Omitting updated_at may cause a version conflict error on some Ghost versions.

Request example

PUT /ghost/api/admin/users/6123abc/
Authorization: Ghost <jwt>
Content-Type: application/json

{"users":[{"id":"6123abc","name":"Jane Doe","bio":"Editor"}]}

Response example

{
  "users": [
    {"id":"6123abc","name":"Jane Doe",
     "bio":"Editor","updated_at":"2025-01-10T12:00:00.000Z"}
  ]
}

Invite new staff user

• Method: POST
• URL: https://{site}/ghost/api/admin/invites/
• Watch out for: Staff users cannot be created directly via POST /users/. The only creation path is sending an invite. The invited user must accept via email link before a user record is created. role_id must be a valid UUID from GET /roles/.

Request example

POST /ghost/api/admin/invites/
Authorization: Ghost <jwt>
Content-Type: application/json

{"invites":[{"email":"new@example.com","role_id":"<role_uuid>"}]}

Response example

{
  "invites": [
    {"id":"inv_abc","email":"new@example.com",
     "status":"sent","created_at":"2025-01-10T12:00:00.000Z"}
  ]
}

List pending invites

• Method: GET
• URL: https://{site}/ghost/api/admin/invites/
• Watch out for: Invites expire after 7 days. Expired invites remain in the list with status expired until deleted.

Request example

GET /ghost/api/admin/invites/
Authorization: Ghost <jwt>

Response example

{
  "invites": [
    {"id":"inv_abc","email":"new@example.com",
     "status":"sent","expires":"2025-01-17T12:00:00.000Z"}
  ]
}

Delete staff user

• Method: DELETE
• URL: https://{site}/ghost/api/admin/users/{id}/
• Watch out for: Deleting a user permanently removes them and reassigns their posts to the Owner. The Owner user cannot be deleted via API.

Request example

DELETE /ghost/api/admin/users/6123abc/
Authorization: Ghost <jwt>

Response example

HTTP 204 No Content

List roles

• Method: GET
• URL: https://{site}/ghost/api/admin/roles/
• Watch out for: Role UUIDs are instance-specific and must be fetched dynamically; do not hardcode them across Ghost installations.

Request example

GET /ghost/api/admin/roles/
Authorization: Ghost <jwt>

Response example

{
  "roles": [
    {"id":"uuid-admin","name":"Administrator"},
    {"id":"uuid-editor","name":"Editor"},
    {"id":"uuid-author","name":"Author"}
  ]
}

• Rate limits: Ghost does not publish explicit rate-limit tiers in official documentation. Self-hosted instances have no enforced API rate limits by default. Ghost Pro (managed hosting) may apply undocumented infrastructure-level throttling.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: No official rate-limit headers or documented thresholds found in Ghost Admin API docs as of 2025.
• Pagination method: offset
• Default page size: 15
• Max page size: 15
• Pagination pointer: page / limit

• Webhooks available: Yes
• Webhook notes: Ghost Admin API supports webhooks configurable via Settings → Integrations or via POST /webhooks/. Webhooks fire on content and member lifecycle events. Staff user lifecycle events (user.added, user.edited, user.deleted) are available.
• Alternative event strategy: Polling GET /users/ on a schedule if webhooks are not feasible.
• Webhook events: user.added, user.edited, user.deleted, member.added, member.edited, member.deleted, post.published, post.unpublished, post.added, post.edited, post.deleted, site.changed

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Ghost has no native SCIM 2.0 support on any plan.
• No native SSO (SAML/OIDC) support; third-party solutions (e.g., miniOrange) are required.
• Staff user provisioning must be done via the Admin API invite flow.

Provision a new staff editor: fetch role UUIDs dynamically from GET /ghost/api/admin/roles/ - they are instance-specific and must never be hardcoded - then POST /ghost/api/admin/invites/ with the target email and role UUID.

Automate only to this point; the invitee must accept via email link before a user record exists in /users/. Invites expire after 7 days and remain in the list with status expired until explicitly deleted.

Suspend a staff user without deleting their content: PUT /ghost/api/admin/users/{id}/ with {"users":[{"id":"{id}","status":"inactive"}]}. This blocks login while preserving posts. The Owner account cannot be set to inactive via API.

Audit full staff access: GET /ghost/api/admin/users/?limit=all&include=roles retrieves all active staff (default page size is 15; limit=all is required for complete results). Follow with GET /ghost/api/admin/invites/ - pending invitees do not appear in /users/ until accepted, so both endpoints are required for a complete access picture.

Provision a new staff editor

1. GET /ghost/api/admin/roles/ to retrieve the UUID for the 'Editor' role.
2. POST /ghost/api/admin/invites/ with body {"invites":[{"email":"editor@example.com","role_id":"<editor_uuid>"}]}.
3. The invitee receives an email; they must click the link and set a password to activate their account.
4. After acceptance, GET /ghost/api/admin/users/?filter=email:'editor@example.com'&include=roles to confirm the user record exists with status active.

Watch out for: There is no way to programmatically complete the invite acceptance step - it requires human interaction via email link. Automate only up to sending the invite.

Suspend (deactivate) a staff user

1. GET /ghost/api/admin/users/?filter=email:'user@example.com' to retrieve the user's id.
2. PUT /ghost/api/admin/users/{id}/ with body {"users":[{"id":"{id}","status":"inactive"}]}.
3. Confirm response contains "status":"inactive".

Watch out for: Setting status to inactive prevents login but does not delete the user or their content. The Owner account cannot be set to inactive via API.

Audit all staff users and their roles

1. GET /ghost/api/admin/users/?limit=all&include=roles to retrieve all staff users with role data in a single request.
2. GET /ghost/api/admin/invites/ to retrieve any pending invites not yet accepted.
3. Combine both lists to produce a full picture of current and pending staff access.

Watch out for: Pending invitees do not appear in /users/ until they accept the invite. Always check /invites/ separately to audit who has been granted access but not yet activated.

The invite-only provisioning model is the primary automation trap: there is no POST /users/ endpoint, so any pipeline that assumes it can create a user record programmatically will fail silently or error. The human acceptance step is non-negotiable and must be documented in any runbook.

JWT generation is error-prone: the secret component of the Admin API Key is hex-encoded and must be decoded with Buffer.from(secret, 'hex') before use as the HMAC signing key. Passing the raw string produces a valid-looking but incorrect signature that Ghost will reject.

Tokens must also expire within 5 minutes; long-lived tokens are rejected at the API layer.

Ghost Pro does not publish rate-limit thresholds or expose rate-limit headers, so backoff logic cannot be tuned to documented limits - implement conservative exponential backoff by default.

On Ghost Pro, the me endpoint returns an integration pseudo-user, not a real staff account, which can produce misleading results if used for identity resolution in an identity graph context.