Workload identity federation
Contents
Note: PostHog doesn't support any workload provider for workload identity federation yet. This page and the provider pages describe how the feature works so you can plan for it. Until a provider is supported, use a personal API key.
hog is PostHog's new CLI. It isn't released yet. Every hog command on these pages is a beta preview of how it works once hog is released, and the details can change. Until then, use posthog-cli with a personal API key, as its authentication docs describe.
Workload identity federation lets a workload you trust, such as a CI job, get a short-lived PostHog token without storing an API key as a secret. The workload proves who it is with the OIDC token its provider issues for each run. PostHog swaps that for a token that works on one project for about 10 minutes.
Other platforms have the same idea under different names. Azure calls it a federated identity credential, AWS a role trust policy, Google Cloud a workload identity provider, and PyPI and npm call it trusted publishing. PostHog's trust policies follow the same OIDC model: an issuer, a subject, and conditions on the token's claims.
Supported CI providers
Each provider page explains what the job needs, which claims a policy matches, the presets PostHog offers, and the workflow snippet.
| Provider | Issuer | Guide |
|---|---|---|
| GitHub Actions | https://token.actions.githubusercontent.com | Workload identity for GitHub Actions |
| GitLab.com | https://gitlab.com | Workload identity for GitLab.com |
| Depot CI | https://identity.depot.dev | Workload identity for Depot CI |
More providers may follow later.
How it works
- An organization admin adds a trusted workload to a project. This creates a trust policy that names the provider, the workload's subject, and the conditions a token must meet, such as a branch or an environment, plus the scopes those tokens carry.
- The workload asks its provider for an OIDC token whose audience is your PostHog instance.
- The workload sends that token to PostHog's token endpoint, naming the project.
- PostHog checks the token's signature, issuer, audience, and expiry, finds the project's trust policy that matches the token's claims, and returns a PostHog access token.
- The workload calls the PostHog API with that token until it expires, then exchanges a new OIDC token.
Workload tokens act as the oldest owner of the project's organization, limited to the project and to the scopes in the policy. Changes they make show up in the activity log under the workload, named with the claims its provider records, for example the repository, workflow, and run, with a link to the run and the trust policy.
Trusted workloads
Find trusted workloads in your project settings, under Trusted workloads. Only organization admins and owners can see them, and changing one asks you to log in again if you haven't recently.
Each trust policy has:
- Provider - the issuer PostHog trusts for this policy.
- Subject and name - the repository or project's ID and its readable name, from the claims the provider names. For GitHub Actions and Depot CI these are
repository_idandrepository, and for GitLab.com they'reproject_idandproject_path. Both must match. The ID never changes, so a repository that is deleted and created again with the same name doesn't match. - Conditions - claims the token must carry with an exact value, such as a branch or an environment. Each provider lists the claims a policy can use, and when it lists any, a policy must set at least one. A condition you leave empty matches any value. A token that doesn't carry a condition's claim never matches. Values are matched exactly, without wildcards.
- Scopes - every token from the policy gets all of these scopes, and no others.
When more than one policy matches a token, the most specific one wins: a policy with more conditions beats one with fewer. If two are equally specific, the older one wins.
Turning a policy off, editing it, or deleting it stops its tokens from working within about 10 seconds. Every change emails the organization's admins and owners and appears in the activity log.
Add a trusted workload in settings
- In your project settings, go to Trusted workloads and add a trusted workload.
- Pick the provider.
- In Repository, enter the repository or project name and click Find. PostHog looks up its ID. If PostHog can't find it, enter the ID in the field that appears instead. Each provider page says where to find the ID.
- Under Which runs can get a token, pick a preset, or pick Custom to set a claim and value yourself.
- Pick the scopes the workload needs.
- Save. PostHog shows the workflow snippet for your provider, with a button to copy it.
Scopes that need care
A policy can grant almost any scope. Some scopes let a token do things that reach beyond the project, last longer than the token, or touch credentials. PostHog shows a warning next to these scopes when you pick them for a trusted workload or a personal API key, and on the approval page. Add them only when the workload needs them.
A few scopes can never be granted to a workload, because they would let a token outlive itself, change its own policy, or read one person's private data:
workload_trust_policyandworkload_trust_policy_requestproject:write, which can rotate the project's secret tokenuser:write, which changes the account of the organization owner the token acts astask:write,conversation:write,signal_scout:write,business_knowledge:write,autoresearch:write, andhog_flow:write, which start agent runs with their own longer-lived tokens (a workflow can create a task)streamlit_app, which hands out a one-hour token for a running appwebhook:write,batch_export:write, andsubscription:write, which set up data feeds or emails that keep sending after the token expiressharing_configuration, because a public sharing link keeps working after the token expiresconversation:readandtask:read, because a workload token acts as an organization owner, and these read that person's private PostHog AI conversations and tasks
Asking an admin for a trusted workload
Any project member can ask for a trusted workload. A request grants nothing on its own. It gives you an approval link to send to an organization admin or owner. They open the link, review the policy, who asked for it and, for an OAuth token, through which app, and approve or reject it. Approving creates the trust policy. Requests expire after 24 hours and can't be edited.
Ask with hog ci setup (beta)
Once hog is released, run hog ci setup in your repository:
The command:
- Detects the provider from your git remote and the CI files in the repository, and reads
owner/repoor the GitLab project path. - Looks up the repository or project's ID.
- Turns
--branch mainor--environment productioninto the matching preset, and adds a scope for each--scopeyou pass. - Creates a policy request and waits for an admin to approve it. If you stop waiting, run
hog ci setup --waitto pick it up again. - Prints the workflow snippet for your provider.
Ask through the API
Send a request with an OAuth token that has the workload_trust_policy_request:write scope:
The keys in conditions are claim names from the provider's OIDC token, and only the claims the provider lists are allowed. The response includes an approval_url to send to an admin.
Exchanging a token
Send the OIDC token to the token endpoint as a form-encoded RFC 8693 token exchange:
resource names the project: your PostHog host followed by /api/projects/<project_id>. Use the project's ID, not the ID of one of its environments.
A successful response looks like this:
The token never outlives the OIDC token it came from, and there is no refresh token. When a call needs a scope the policy doesn't have, the API answers with a 403 and a WWW-Authenticate header naming the missing scope. Ask an admin to add it to the policy.
The exchange is rate limited per subject. Over the limit, it returns a 429 with the workload_rate_limited error.
How hog exchanges tokens (beta)
Once hog is released, it does the exchange for you:
- It asks the provider for an OIDC token whose audience is the PostHog host it sends the token to. That host is
HOG_HOST, or else the host in your project's hog config, or elsehttps://us.posthog.com. - It sends the RFC 8693 exchange to
/oauth/token/and keeps the PostHog token in memory only. It never writes the token to disk. - It exchanges again when the token is close to expiring, or after the API answers with a
401. - It picks credentials in this order: a personal API key, then the workload token, then a stored login. Remove any personal API key from the job's environment, or hog uses that instead of the workload token.
Errors
A refused exchange returns an OAuth error body with an error_code and an error_uri that links to the matching entry below.
workload_invalid_request
The request is missing subject_token, uses an unsupported subject_token_type, or resource isn't a project URL on this PostHog instance.
workload_issuer_not_allowed
The OIDC token comes from an issuer PostHog doesn't trust. Only the supported providers are trusted.
workload_token_invalid
PostHog couldn't verify the OIDC token: it expired, its audience isn't your PostHog instance, its signature doesn't verify, or it lacks a claim PostHog needs, such as the subject or the name.
workload_provider_unavailable
PostHog couldn't fetch the provider's signing keys. Try again in a minute.
workload_no_matching_policy
No enabled trust policy in the project matches the token's subject, name, and conditions. The same error covers a project or environment ID that doesn't exist, so the exchange can't be used to find out which projects exist.
workload_policy_request_pending
No policy matches yet, but a request for one is waiting for an admin. The error includes the request's approval link.
workload_no_usable_scopes
The matching policy only grants scopes a workload token can't use. Ask an admin to edit the policy.
workload_rate_limited
Too many exchanges for the same subject in a short time. The response has a 429 status. Wait, then try again. A job that reuses its PostHog token until it's close to expiring, as hog does, makes fewer exchanges.
workload_no_owner
The project's organization has no active owner for workload tokens to act as.
workload_not_configured
This PostHog instance isn't set up to issue workload tokens.





