Authentication

Every GrainQL surface identifies your account by the tenant alias. The dashboard shows it as Workspace ID in Settings, General settings. GrainQL Tag sends the alias and nothing else. Analytics Web adds one of three authentication strategies. The Query API needs an API key, and the MCP server uses OAuth 2.1.

The surfaces

Surface	Credential	Header	Where the secret lives
GrainQL Tag	Tenant alias only. `GrainTagConfig` has no authentication field.	None	Nowhere. The alias is public.
Analytics Web, `NONE`	Tenant alias only	None	Nowhere. The alias is public.
Analytics Web, `SERVER_SIDE`	Secret key	`Authorization: Bearer <secret>`	An environment variable on the server
Analytics Web, `JWT`	A JWT from your own login system	`Authorization: Bearer <token>`	Your login system. GrainQL holds the public key or the JWKS endpoint.
Query API	API key with the “Query API” permission	`X-API-Key`	An environment variable on the server
MCP server	OAuth 2.1 access token	Set by the MCP client	The MCP client

The three strategies are for the ingestion of events. The Query API key and the MCP token are separate. A Query API key works with every SDK strategy.

Turn on SERVER_SIDE or JWT

A workspace starts with NONE. SERVER_SIDE and JWT are locked for each workspace until GrainQL support turns them on. The lock does not depend on the plan. While the lock is on, the Client authentication settings page shows the current strategy, and nobody can change it. To remove the lock, send an email to support@grainql.com with the name of the workspace. After support removes the lock, an admin or an owner can select the strategy at https://grainql.com/dashboard/settings/authentication.

NONE

NONE is the default strategy of Analytics Web. The SDK sends events and reads configurations with the tenant alias and no credential:

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'NONE'
});

Use NONE for a public website, a landing page, development, or an app without user login.

Do not use NONE with sensitive data. Anyone who holds the tenant alias can send events and read every configuration value.

SERVER_SIDE

SERVER_SIDE sends a secret key with every request in the Authorization: Bearer <secret> header. The server validates the secret before it processes the request. Use it in a Node.js backend, a server-side API route, a serverless function, or any other environment that keeps a secret out of the browser. To get the secret key:

Open Settings, then API keys, at https://grainql.com/dashboard/settings/api-keys.
Click Create key. Select the Send events access. Then create the key.
Copy the key and store it in an environment variable. The dashboard shows the key one time.
Open Settings, then Client authentication, at https://grainql.com/dashboard/settings/authentication. Select Server secret and save.

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY
});

Never put the secret key in browser code. A bundle is public, and anyone who reads it can send events as your tenant.

JWT

JWT is for a browser app that already has a user login. Before each request, the SDK calls authProvider.getToken() and sends the result in the Authorization: Bearer <token> header. getToken returns a string or a Promise<string>. Configure the token check in Settings, Client authentication. Select Your own JWTs. Then fill in the Token check card. GrainQL checks the signature, the issuer, and the audience of every token.

Field	Holds	Required
Issuer	The `iss` claim of the token, for example your Auth0 domain	Yes
Audience	The `aud` claim of the token	Yes
JWKS address	The JWKS endpoint. If it is empty, GrainQL finds it from the issuer.	No
Algorithm	Any RSA algorithm (`RS256`, `RS384`, `RS512`), or one of them	No
Public key	A PEM public key, for when you cannot publish a JWKS address	No

Then pass an authProvider to the SDK:

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'JWT',
  authProvider: {
    async getToken() {
      return await yourAuthSystem.getAccessToken();
    }
  }
});

With Auth0, getToken is getAccessTokenSilently from @auth0/auth0-react. With NextAuth.js, getToken returns session.accessToken from getSession(). login({ authToken }) also sets the strategy to JWT at run time. Read Identify users.

The user ID must match the token

With JWT, the user ID in an event must equal the sub claim of the token. The server rejects an event with another user ID. This rule stops one user from sending events as another user.

// JWT payload: { sub: "user_123" }
grain.setUserId('user_123');
grain.track('button_clicked', { button: 'submit' });

grain.setUserId('user_456');
// The server rejects the events that follow. "user_456" is not the "sub" claim.

One configuration for two environments

The strategy is a configuration value, so one code path can serve development and production:

const isProduction = process.env.NODE_ENV === 'production';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: isProduction ? 'JWT' : 'NONE',
  authProvider: isProduction ? authProvider : undefined
});

Query API key

The Query API reads events out of GrainQL. It needs an API key with the “Query API” permission. The key is separate from the SDK strategies and from the secret key. An admin or an owner creates the key:

Open Settings, then API keys, at https://grainql.com/dashboard/settings/api-keys.
Click Create key.
Enter a Name, for example Query API key.
Under Access, select Query API.
Under Expires, choose 30 days, 90 days, 1 year, or 2 years. Then create the key.
Copy the key and store it in an environment variable. The dashboard shows the key one time.

Send the key in the X-API-Key header:

curl -X POST https://queryapis.grainql.com/v1/api/query/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{"event": "page_viewed"}'

The response is an array of events:

[
  {
    "eventName": "page_viewed",
    "userId": "user_123",
    "eventTs": "2024-01-15T10:30:00Z",
    "properties": {
      "page": "/home",
      "referrer": "https://google.com",
      "device": "desktop"
    },
    "eventDate": "2024-01-15",
    "insertId": "unique-event-id"
  }
]

Use a Query API key on a server only. A key in browser code lets anyone read every event of your tenant.

Read Export and query data for the endpoints and the rate limits.

MCP server

An AI assistant authenticates with OAuth 2.1. The MCP client registers itself, you approve the scopes on a consent screen, and the client receives an mcpat_… access token. No secret is copied by hand. Read MCP server.

Dashboard session

The dashboard itself signs you in with Auth0. It caches the access token for about 4 minutes and refreshes it. If the session expires after a long idle period, the dashboard shows an error with a Reload page action, and a tab that stays open redirects to the login page. Reload the page to continue. Your work is preserved.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

The surfaces

Turn on SERVER_SIDE or JWT

NONE

SERVER_SIDE

JWT

The user ID must match the token

One configuration for two environments

Query API key

MCP server

Dashboard session

​The surfaces

​Turn on SERVER_SIDE or JWT

​NONE

​SERVER_SIDE

​JWT

​The user ID must match the token

​One configuration for two environments

​Query API key

​MCP server

​Dashboard session

The surfaces

Turn on SERVER_SIDE or JWT

NONE

SERVER_SIDE

JWT

The user ID must match the token

One configuration for two environments

Query API key

MCP server

Dashboard session