Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

API keys enable non-interactive authentication for the Ghostly SDK, CLI pipelines, and MCP integrations. Instead of a session JWT, clients include the key in an X-Api-Key header with every request. All three management endpoints in this group — list, create, and delete — require an active JWT session to call. This design means you must be logged in to the dashboard (or use another privileged mechanism) to issue or revoke keys.
Keys generated by the ghostly keygen CLI command are stored locally in ~/.ghostly/auth.json on your machine and are not managed by these endpoints. The /v1/api-keys endpoints exclusively manage keys issued through the dashboard.

​
GET /v1/api-keys — List all API keys

Returns all API keys that belong to the authenticated user. For security, only the first 8 characters of each key are returned — the rest is replaced with ••••••••.

​
Authentication

Requires a valid JWT in the Authorization: Bearer <token> header.

​
Response — 200 OK

Returns a JSON array. Each element represents a stored key.
​
id
string
required
UUID that uniquely identifies this key record.
​
label
string
required
The human-readable name assigned when the key was created.
​
key
string
required
The masked key value: the first 8 characters followed by •••••••• (e.g. "a1b2c3d4••••••••"). The full key is never returned by this endpoint.
​
createdAt
string
required
ISO 8601 timestamp of key creation.

​
curl example

curl https://your-ghostly-host/v1/api-keys \
  -H "Authorization: Bearer <jwt>"

​
Example response

[
  {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "label": "CI Pipeline",
    "key": "a1b2c3d4••••••••",
    "createdAt": "2025-03-10T08:00:00.000Z"
  },
  {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "label": "Local Dev",
    "key": "e5f6a7b8••••••••",
    "createdAt": "2025-04-01T12:00:00.000Z"
  }
]

​
POST /v1/api-keys — Create a new API key

Generates a new 64-character hex API key using randomBytes(32).toString('hex') and stores it associated with the authenticated user. The full key is only returned in this creation response — it cannot be retrieved again afterwards.

​
Authentication

Requires a valid JWT in the Authorization: Bearer <token> header.

​
Request body

​
label
string
required
A human-readable name for this key (e.g. "CI Pipeline", "Local Dev"). Must be a non-empty string after trimming whitespace. Used to identify the key in the list view.

​
Response — 201 Created

​
id
string
required
The UUID of the newly created key record.
​
label
string
required
The label as stored (trimmed).
​
key
string
required
The full, unmasked API key. This is the only time the complete key value is available. Copy and store it immediately.
​
createdAt
string
required
ISO 8601 creation timestamp.

​
Example response

{
  "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "label": "CI Pipeline",
  "key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "createdAt": "2025-06-15T09:45:00.000Z"
}
The full API key is only returned once — at creation time. It is stored hashed and cannot be recovered later. Save it immediately in a secure location such as a CI secret store or a password manager. If you lose the key, you must delete it and create a new one.

​
curl example

curl -X POST https://your-ghostly-host/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"label": "CI Pipeline"}'

​
Using the key immediately after creation

# Create the key and capture it
KEY=$(curl -s -X POST https://your-ghostly-host/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"label": "CI Pipeline"}' | jq -r '.key')

# Use it to authenticate subsequent requests
curl https://your-ghostly-host/v1/projects \
  -H "X-Api-Key: $KEY"

​
DELETE /v1/api-keys/:id — Delete an API key

Permanently revokes a key by its record ID. After deletion, any client using that key will receive a 401 Unauthorized on their next request.

​
Authentication

Requires a valid JWT in the Authorization: Bearer <token> header.

​
Path parameters

​
id
string
required
The UUID of the API key record to delete. Must match a key that belongs to the authenticated user.

​
Response — 200 OK

​
ok
boolean
required
Always true when the key was found and deleted successfully.
{ "ok": true }

​
Response — 404 Not Found

Returned when no key with the given id exists, or when the key exists but belongs to a different user. The same response shape is used for both cases to prevent key ID enumeration. 
{ "ok": false, "error": "not found" }

​
curl example

curl -X DELETE https://your-ghostly-host/v1/api-keys/f6a7b8c9-d0e1-2345-fabc-456789012345 \
  -H "Authorization: Bearer <jwt>"
To rotate a key — for example after a suspected leak — create the new key first, update any consumers to use it, then delete the old key. This avoids downtime between the two operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us