Authentication

Every Grain surface identifies your account by the tenant alias that the dashboard shows. Grain 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
Grain 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: Chase <secret>`	An environment variable on the server
Analytics Web, `JWT`	A JWT from your own login system	`Authorization: Bearer <token>`	Your login system. Grain 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.

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: Chase <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 the dashboard at https://grainql.com/dashboard.
Open the settings of your tenant.
Generate or copy the secret key.
Store it in an environment variable.

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 JWT in the settings of your tenant in the dashboard:

The JWT issuer, for example your Auth0 domain.
The JWT audience.
The public key or the JWKS endpoint.

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 Grain. It needs an API key with the “Query API” permission. The key is separate from the SDK strategies and from the secret key.

Open Dashboard → Settings → Authentication at https://grainql.com/dashboard/settings.
Click Generate New Secret.
Enter a name, for example Query API key.
Select the Query API permission.
Copy the key and store it in an environment variable.

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

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

​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

NONE

SERVER_SIDE

JWT

The user ID must match the token

One configuration for two environments

Query API key

MCP server

Dashboard session