ID-JAG (XAA) authentication

ID-JAG (Identity Assertion JWT Authorization Grant, also called XAA) lets your organization's identity provider (IdP), such as Okta, Microsoft Entra ID, or any OIDC-compliant SSO, grant programmatic access to PostHog. Instead of each user creating a personal API key or running an OAuth flow, your IdP issues an ID-JAG that a client exchanges with PostHog for a short-lived access token. You grant, scope, and revoke access centrally in your IdP.

Why use it

ID-JAG keeps authorization decisions in your IdP instead of spreading them across personal keys and per-user OAuth grants:

• No personal API keys to manage: users authenticate with their existing corporate SSO, and clients get tokens on demand.
• Centralized policy: your IdP evaluates its own access policies (group membership, conditional access, etc.) before it issues an ID-JAG.
• Centralized revocation: once your IdP stops issuing ID-JAGs for a user, clients can no longer get new access tokens for them.
• Scoped tokens: the access token carries only the scopes your IdP granted, intersected with what the client requested.

The most common use is connecting AI agents to the PostHog MCP server under central control. See enterprise-managed authorization for the MCP-specific setup.

How it works

1. A user signs in to a client app, such as an AI agent, with your IdP.
2. Your IdP checks its policies and gives the client an ID-JAG for PostHog.
3. PostHog checks the ID-JAG against your XAA configuration and gives the client a short-lived access token that acts as that user.

Requirements

• The Scale or Enterprise platform add-on on your PostHog organization.
• A verified domain in PostHog for the email domain your users sign in with.
• Users who are already members of your PostHog organization. PostHog does not create accounts from ID-JAGs, so provision users with SCIM or SSO first.
• An IdP that can issue ID-JAGs and publishes its signing keys where PostHog can reach them over the internet.
• A client registered with PostHog, such as an MCP client or your own app. Most MCP clients that support enterprise-managed authorization handle this for you.

Setup

1. Verify your domain in PostHog

Go to Organization settings → Authentication and add and verify the domain your users authenticate with (e.g. example.com) under Authentication domains. See the SSO docs for domain verification steps.

2. Configure the trusted IdP

On the same settings page, find XAA authentication and click Configure. You need to be an organization admin. Fill in:

Under Domains, choose All domains to cover every verified domain in your organization, or Selected domains to pick specific ones. Then click Save configuration.

Use one XAA configuration per IdP and domain. If two configurations cover the same IdP and domain, PostHog rejects the request.

3. Register the client

The client app needs a client ID that PostHog recognizes, and your IdP must issue ID-JAGs for that client ID.

• MCP clients: follow the client's enterprise-managed authorization setup. See enterprise-managed authorization.
• Your own app: register an OAuth app with PostHog, then see how to exchange an ID-JAG yourself.

4. Grant the required scopes in your IdP

Configure your IdP to include the scopes each integration needs when it issues ID-JAGs. At minimum, all tokens need user:read. For the MCP server, also include organization:read and project:read. Add any additional API scopes for what you want to do (for example, feature_flag:write to manage flags).

The access token gets only the scopes that both your IdP granted and the client asked for.

Revoking access

• At your IdP: once your IdP stops issuing ID-JAGs for a user, the client can no longer get new access tokens. Existing tokens expire within 2 hours.
• In PostHog: removing the user from the organization, or deactivating them, stops their tokens working on the next request.
• The whole integration: deleting the XAA configuration stops new tokens. Tokens already issued stay valid until they expire.

Troubleshooting

The most common errors when a client requests a token:

For every error code, see what all the error codes mean.

FAQ

curl -X POST https://oauth.posthog.com/oauth/token/ \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=<the ID-JAG JWT from your IdP> \
  -d client_id=<your PostHog client ID> \
  -d client_secret=<your client secret> \
  -d scope="user:read organization:read project:read"

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "user:read organization:read project:read"
}

Further reading

• Enterprise-managed authorization for MCP
• ID-JAG / XAA specification
• SSO
• OAuth integration
• API authentication and scopes