The GraphJSON API key authenticates requests for a workspace. It is powerful: ingestion endpoints can write data, while data and visualization endpoints can query it.
Keep the key server-side#
Store the key in a secret manager or environment variable:
GRAPHJSON_API_KEY=...
Read it only in trusted server code:
const apiKey = process.env.GRAPHJSON_API_KEY;
Security: Never put the key in browser JavaScript, a mobile binary, a public repository, a support ticket, client-visible logs, or a URL you control.
Cross-origin API support does not make a browser request safe. Any key shipped to a browser can be recovered by the person using it.
Authentication format#
GraphJSON APIs currently accept api_key in the JSON request body:
{
"api_key": "your_api_key",
"collection": "product_events"
}
There is no separate public or read-only key. Design your integration as if the key grants workspace-level data access.
Isolate the browser#
For customer-facing analytics:
browser → your server → GraphJSON API
← iframe URL or sanitized data
Your server authenticates the user, adds an allowed user_id or account_id filter, calls GraphJSON with the secret key, and returns only the generated iframe URL or the data the user is permitted to see.
Never accept an arbitrary GraphJSON payload from the browser and simply append the API key. Construct the collection, fields, filters, and allowed graph type on the server.
Treat embed URLs as capabilities#
A generated iframe URL contains an encrypted configuration. It does not visibly expose the API key, but anyone who has the URL can load that chart.
Use embeds only for data appropriate to the intended audience. Do not expose an unfiltered workspace-wide chart and rely on an obscured URL as authorization.
If a key is exposed#
- Remove it from the exposed location.
- Revoke access to the repository, log, build artifact, or client bundle if possible.
- Contact hi@graphjson.com to replace the key.
- Update every server and integration that uses it.
- Review recent collections and dashboards for unexpected activity.
Removing a key from the latest Git commit is not enough if it remains in history.
Minimize sensitive data#
Do not send secrets, credentials, authentication tokens, payment card data, or raw private documents to an analytics event.
Prefer internal IDs over personally identifiable fields. If a workflow only needs account_id, plan, and amount, do not also send a name, email address, and full billing record.
Use separate collections and appropriate retention windows when data has different sensitivity or lifecycle requirements.
Team access#
Workspace team members share access to the workspace’s analytics resources. Review team membership when roles change, and enable two-factor authentication from the dashboard’s Security page for accounts that can access production data.