---
title: Terraform map
description: Where each Auth0 object lives in the repository, and the tests that pin it.
sidebar:
  order: 8
---

Terraform owns declared Auth0 infrastructure; [runtime clients and owner-managed prerequisites](/architecture/auth0#resource-ownership)
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.