Authentication

Secure your API requests with authentication tokens.

Overview

Most Ghost Metrics API requests require authentication. Authentication is handled via a token_auth parameter that identifies who is making the request and what data they can access.

Creating an Auth Token

Step 1: Access Security Settings

1. Log into Ghost Metrics
2. Click the gear icon (Administration)
3. Go to Personal → Security
4. Scroll to the Auth tokens section

Step 2: Create a New Token

1. Click Create new token
2. Confirm your account password when prompted
3. Enter a description (e.g., “Dashboard Integration” or “Reporting Script”)
4. Optionally check Only allow secure requests — the token will then only work when sent in a POST body, never in a URL (recommended for production)
5. Optionally set an expiry date
6. Click Create new token
7. Copy the token immediately — it’s shown only once

Step 3: Store Securely

• Store tokens in environment variables or secure configuration
• Never commit tokens to version control
• Never expose tokens in client-side JavaScript

Using Your Token

In the URL (GET Request)

Add token_auth as a query parameter:

https://example.ghostmetrics.cloud/?module=API
  &method=VisitsSummary.get
  &idSite=1
  &period=day
  &date=yesterday
  &format=JSON
  &token_auth=YOUR_TOKEN_HERE

In the Request Body (POST Request) — Recommended

Send the token in the POST body for better security:

curl -X POST 'https://example.ghostmetrics.cloud/?module=API&method=VisitsSummary.get&idSite=1&period=day&date=yesterday&format=JSON' \
  -d 'token_auth=YOUR_TOKEN_HERE'

POST requests prevent the token from appearing in server logs and browser history.

Token Permissions

Your token inherits the permissions of your user account:

A token cannot have more permissions than the user who created it.

Security Best Practices

Do

• ✅ Use POST requests for API calls when possible
• ✅ Store tokens in environment variables
• ✅ Create separate tokens for different applications
• ✅ Use descriptive names so you know what each token is for
• ✅ Delete tokens you no longer need
• ✅ Rotate tokens periodically (every 6-12 months)

Don’t

• ❌ Put tokens in client-side JavaScript
• ❌ Commit tokens to Git repositories
• ❌ Share tokens between team members (create individual tokens)
• ❌ Use tokens in URLs if POST is an option
• ❌ Keep old, unused tokens active

”Only Allow Secure Requests”

The checkbox at creation time controls how a token may be used:

• Unchecked — the token works in GET URLs and POST bodies. Convenient for testing, but tokens in URLs can end up in server logs and browser history.
• Checked — the token only works sent as a POST parameter. Recommended for production applications. (Don’t enable it for a token you need to embed in a GET URL, such as a report iframe.)

Treat every token like a password — it grants the same data access as your login.

Managing Tokens

Viewing Existing Tokens

1. Go to Administration → Personal → Security
2. See all your tokens under Auth tokens, with their descriptions and usage

Revoking a Token

If a token is compromised or no longer needed:

1. Go to Administration → Personal → Security
2. Find the token in the list
3. Click Delete or the trash icon
4. Confirm deletion

The token is immediately invalidated.

Regenerating a Token

You cannot change an existing token. To replace a compromised token:

1. Create a new token
2. Update your application to use the new token
3. Delete the old token

Anonymous Access

Some Ghost Metrics instances allow anonymous access to certain data. If your statistics are public:

• Use token_auth=anonymous for public data
• Anonymous access is read-only
• Not available for private installations (typical for healthcare)

Most Ghost Metrics healthcare deployments require authentication for all API access.

Session Tokens

When exporting data from the Ghost Metrics interface, you may see URLs with force_api_session=1. These use temporary session tokens that:

• Only work while you’re logged in
• Change each time you log in
• Stop working when you log out

For permanent API access, create a proper auth token instead of using session tokens.

Troubleshooting

”You are not authorized”

• Verify your token is correct (no extra spaces)
• Check the token hasn’t been deleted or expired
• Confirm your user has access to the requested website
• If the token was created with Only allow secure requests, it won’t work in a GET URL — send it in the POST body

”Invalid token”

• Token may have been deleted or reached its expiry date
• Token may be malformed
• Check for copy/paste errors

Token Suddenly Stopped Working

• Check whether it was deleted from the Auth tokens list or hit an expiry date you set at creation
• Tokens are independent secrets — if in doubt, create a fresh token and retire the old one

Example: Secure Token Usage

Environment Variable (Recommended)

# Set environment variable
export GHOST_METRICS_TOKEN="your_token_here"

import os
import requests
 
token = os.environ.get('GHOST_METRICS_TOKEN')
url = "https://example.ghostmetrics.cloud/"
 
response = requests.post(url, data={
    'module': 'API',
    'method': 'VisitsSummary.get',
    'idSite': 1,
    'period': 'day',
    'date': 'yesterday',
    'format': 'JSON',
    'token_auth': token
})

Configuration File

// config.json (add to .gitignore!)
{
  "ghost_metrics": {
    "url": "https://example.ghostmetrics.cloud/",
    "token": "your_token_here",
    "site_id": 1
  }
}

Next Steps

• Making Requests — Structure your API calls
• Parameters Reference — Available parameters
• Code Examples — Working implementations