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. Enter a description (e.g., “Dashboard Integration” or “Reporting Script”)
3. Choose the token type:
   • All requests — Token works for GET and POST requests
   • Only POST requests — More secure, requires POST method
4. Click Create
5. Copy the token immediately — it won’t be shown again

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

Token Types

All Requests Token

• Works with both GET and POST HTTP methods
• Convenient for testing and simple integrations
• Less secure because GET requests can be logged

POST-Only Token

• Only works with POST HTTP method
• More secure — token never appears in URLs
• Recommended for production applications

Managing Tokens

Viewing Existing Tokens

1. Go to Administration → Personal → Security
2. See all your tokens under Auth tokens
3. Each shows description, creation date, and last used

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
• Confirm your user has access to the requested website
• Ensure the token type matches your request method (POST-only tokens won’t work with GET)

“Invalid token”

• Token may have been deleted
• Token may be malformed
• Check for copy/paste errors

Token Not Working After Password Change

• Tokens remain valid after password changes
• If tokens stopped working, they may have been manually deleted

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