Terraform map

Where each Auth0 object lives in the repository, and the tests that pin it.

Terraform owns declared Auth0 infrastructure; runtime clients and owner-managed prerequisites remain separate. Alchemy owns the declared Workers. The files below are the ones that shape the API and MCP integration; the repository’s infra/terraform/auth0/README.md covers the rest.

File in `infra/terraform/auth0`	Holds
`variables.tf`, `prod.tfvars.json`	`shop_api_origin` and `shop_mcp_origin`, validated as https bare hosts with no trailing slash
`api.tf`	Shop API resource server and scopes; the storefront and backoffice API clients and grants; the website grant
`mcp.tf`	The MCP resource server and scopes; the third-party default grant; the MCP Custom API client and its OBO grant
`poppy-direct.tf`	The Auth0 proxy’s user grants on the Shop API and MCP resource; the web and MCP agent forwarder clients and grants
`personal-agents.tf`	Independent `agents` connection and client, invited-agent CTE profile, login Action and Auth0 proxy configuration outputs
`backoffice.tf`	`ops_management`, the read-only Management client for the API’s operator reads
`contract-moves.tf`	`moved` blocks that keep existing client identities under their current names
`tenant.tf`	Opt-in tenant settings: Dynamic Client Registration, compatibility resource parameters and prevent-destroy
`main.tf`	The Poppy-Users domain connection and website refresh-token policy
`outputs.tf`	Values handed to the Workers’ stacks: audience and client identifiers, and client secrets as sensitive outputs

Outputs handed to the deploy

Output	Consumer	Carries
`shop_stack_env`	Webshop	Login domain, website client, storefront and web-agent-forwarder client credentials, database connection
`api_stack_env`	API	Issuer, JWKS URL, audience, caller client IDs, Auth0 proxy settings and Management clients
`mcp_stack_env`	MCP server	Issuer, JWKS URL, token endpoint, MCP and MCP-agent-forwarder client credentials
`personal_agent_proxy_auth0_config`, `personal_agent_client_secret`	Proxy Auth0	Invited-agent `personalAgents` configuration and its separately bound secret
`backoffice_api_env`	Backoffice	Backoffice API client id, secret and token endpoint

Tests that pin it

Terraform test files (tests/shop_api.tftest.hcl, tests/shop_mcp.tftest.hcl, tests/poppy_direct.tftest.hcl, tests/tenant.tftest.hcl) run against a mocked provider and assert, among others:

every resource uses the RFC 9068 profile and client-grant-required for users;
the MCP Custom API client is linked to its own identifier and allows only On-Behalf-Of;
the third-party default grant exists only for the MCP resource and holds only agent scopes;
the OBO grant excludes payment_methods:write, account:security, guest and ops:read;
the storefront grant excludes account:*, payment_methods:* and ops:*, and the backoffice grant is exactly ops:read;
Poppy uses only the canonical MCP resource;
the website refresh-token policies include both the Shop API and My Account;
no resource identifier ends with a slash, and a non-https origin, a path, or a trailing slash is rejected.

apps/api/contracts/scopes.terraform.test.ts pins scope names, descriptions and order against the code catalogue.

Adopting the tenant singleton

Keep manage_tenant_settings=false. The owner sets it to true in a scratch plan and imports auth0_tenant.this[0] using the tenant ID. Review the plan and pin any unrelated drift to its live values: only the compatibility resource profile and DCR flag may change. Then set the flag in production variables. Release tenant settings separately, verify existing login screens, release the domain connection, and finally release the MCP resource and Workers.