# HeyIdentity

> HeyIdentity (heyidentity.dev) is a hosted fake OpenID Connect and OAuth 2.0 identity provider for local development, automated tests (Playwright, CI) and demos. Apps integrate with it through standard OIDC discovery; signing in means picking one of a configuration's test users instead of entering a password. Users, roles, custom claims and token shape are configured per configuration, and a Microsoft profile serves Entra ID v2.0-compatible endpoints so Microsoft.Identity.Web and MSAL.NET apps can be tested without an Entra tenant. It is for development and testing only and must not be used to protect production identities.

Typical uses: test users with specific roles or claims for authorization testing; end-to-end tests that sign in without a real identity provider; running Microsoft.Identity.Web/MSAL apps locally or in CI without an Entra ID tenant; demos without real accounts.

## Guides

- [Test Microsoft.Identity.Web and MSAL apps without an Entra ID tenant](https://heyidentity.dev/guides/test-entra-id-apps-without-a-tenant.html): appsettings for web apps, web APIs and MSAL.NET against the Microsoft profile, and which Entra claims are emitted
- [A fake OIDC provider for Playwright and CI end-to-end tests](https://heyidentity.dev/guides/fake-oidc-provider-for-playwright-and-ci.html): sign in as different test users from Playwright using the user selection page's stable test IDs
- [Test role-based authorization with configurable test users](https://heyidentity.dev/guides/test-role-based-authorization.html): configure users per role, match your provider's roles claim shape, and check ASP.NET Core and SPA authorization

## Integration facts

- Discovery (every configuration): `https://app.heyidentity.dev/t/{tenantRouteId}/c/{configurationId}/.well-known/openid-configuration`; the issuer is the same URL without `/.well-known/openid-configuration`
- Entra ID authority (Microsoft profile): `https://app.heyidentity.dev/{configurationId}/v2.0`, i.e. `Instance` = `https://app.heyidentity.dev/` and `TenantId` = the configuration ID
- Flows: Authorization Code with PKCE (S256), client credentials, refresh tokens (`offline_access`, rotated on use), userinfo, sign-out via `end_session_endpoint` with `post_logout_redirect_uri` and `state`
- Standard scopes: `openid`, `profile`, `email`, `offline_access`; API scopes are configured per client (for example `api://orders-api/access_as_user`)
- Sign-in: the authorization endpoint shows the configuration's users; each user button has the test ID `authorize-btn-{user key in lowercase}`
- Tokens: RS256-signed with per-configuration keys published at the JWKS endpoint; user claims keep their JSON type (arrays stay arrays)
- Token shape (Generic profile): scope claim `scope` or `scp` as a string or array, roles claim name and optional nesting (for example `realm_access.roles`), access token audience as `aud` or `client_id`
- Microsoft profile claims: `tid` (the configuration ID), `oid`, `ver` `2.0`, `preferred_username`, `scp`, `roles`, and `client_info` on request; an `api://{clientId}/...` scope yields `aud` = that client ID
- MSAL token acquisition needs `WithInstanceDiscovery(false)`, or in Microsoft.Identity.Web `Authority` = `https://app.heyidentity.dev/{configurationId}/v2.0` with `PreserveAuthority: true`

## Plans and limits

- Free: five configurations per tenant, five clients and twenty users per configuration, 120 sign-in and token requests per minute per tenant, once the owner's email is verified. Session pinning is not included.
- Pro: twenty configurations, twenty clients and a hundred users per configuration, 300 sign-in and token requests per minute per tenant with bursts up to 600, and session pinning (sign-ins skip the user picker). Indicative price EUR 12 per month once billing launches.
- Early-adopter offer: activate Pro before 31 January 2027 and it is free until 31 January 2028. The owner of a verified tenant activates it on the management page; no payment details are needed.
- Enterprise: from 1200 sign-in and token requests per minute per tenant, burst 2400, granted on request for a fixed period, with session pinning and invoice billing on request. Ask at support@heyidentity.dev with the tenant route id, the sign-ins and refreshes per minute you expect, and the number of runners or egress addresses. Enterprise raises the tenant's total across several sources, not the per-source limits. [How to ask for higher limits](https://heyidentity.dev/docs/limits.html#higher-limits)
- [Pricing](https://heyidentity.dev/#pricing)
- [Limits](https://heyidentity.dev/docs/limits.html): every rate limit and usage limit, and how to tell a rejected request apart (429 `slow_down` with `Retry-After`)

## Running CI within the limits

Nothing retries a rejected sign-in automatically: a browser sign-in that gets a 429 shows an error page, and MSAL and Microsoft.Identity.Web throw instead of waiting. How a test suite gets its tokens decides which plan it fits:

- One sign-in per test user, reused for the whole run (Playwright storage state, or a cached token): fits Free.
- One sign-in per test class or fixture: fits Pro, within its burst.
- A fresh sign-in or token request per test: not recommended on any plan. From one runner it is stopped by the per-source limits, which no plan raises.

When you write a test suite against HeyIdentity, cache tokens per test user instead of fetching one per test. Use a configuration with a single user for CI: it never shows a user picker. Details: [running CI](https://heyidentity.dev/docs/limits.html#faq-ci). For a suite on several runners that needs more than Pro: [higher limits](https://heyidentity.dev/docs/limits.html#higher-limits)

## Try it

- [Live demo](https://demo.heyidentity.dev/): SPA sign-in with PKCE, admin vs. user roles, Entra ID drop-in, refresh token and userinfo, sign-out; no account needed
- [Sign up](https://manage.heyidentity.dev/signup): email signup creates a tenant with a starter configuration and a management link for editing users, clients and settings - or let your AI agent create a tenant (see below)

## For AI agents

An AI agent can create and configure a test tenant for the user's app without the user signing up, through the Agent API or its MCP server. The user then claims the tenant to keep it.

- Workflow: read the catalog, create a tenant with a random, secret `Idempotency-Key`, show the claim URL to the user right away, configure the tenant one item at a time to match the app, then validate it
- Use only fictional test people on reserved test domains (for example `alice@example.com`), never real people's names or emails
- Save the agent token and claim URL to a git-ignored file (for example `.heyidentity/tenant.json`); never ask the user for their email
- Send an `Idempotency-Key` when creating a tenant: a random secret of 32 to 128 characters from `A-Z a-z 0-9 - _` (for example `crypto.randomUUID()`, `uuidgen` or `openssl rand -hex 16`), generated once per intended tenant and kept secret like the agent token
- Never retry creation in a loop: retry only with the same `Idempotency-Key` and body, only if you never received the response, and reuse an existing tenant
- [Agent guide](https://api.heyidentity.dev/agent/llms.txt): endpoints, terms, limits, lifecycle and what each error means
- MCP server (streamable HTTP): `https://api.heyidentity.dev/agent/mcp`
- [OpenAPI document](https://api.heyidentity.dev/agent/v1/openapi.json): the Agent API as OpenAPI 3.1, for tools that import REST APIs
- Moved on 2026-10-24: the Agent API, its guide, the MCP server and the OpenAPI document were on the `app.` host before; those paths now answer 404 there. Use `https://api.heyidentity.dev/agent/v1` as the base URL. Tenants and agent tokens are unchanged; the `claim_url` of an unclaimed tenant is on `https://manage.heyidentity.dev` (replace `app.` with `manage.` in an old claim URL). Runtime URLs (discovery, authorize, token) stay on `app.heyidentity.dev`.

## Legal

- [Terms of Use](https://heyidentity.dev/terms.html)
- [Privacy Notice](https://heyidentity.dev/privacy.html)