One catalog, one FlowState tenant

Each Partner Central catalog in your AWS account (Sandbox or Production) can be connected to one FlowState tenant only. This stops Partner Central changes from going to two tenants, for example a test tenant and a live tenant that both use your Sandbox catalog.

The connector enforces this with a catalog lock: a Systems Manager parameter in your AWS account. Read this page when a connector deploy or Test connection is refused because of the lock.

What the connector creates

The CloudFormation stack and the OpenTofu module create the lock first, before any other resource:

Catalog	Parameter name	Region
Production	`/flowstate/apn-connector/lock/AWS`	us-east-1
Sandbox	`/flowstate/apn-connector/lock/Sandbox`	us-east-1

The value names the catalog and the FlowState tenant and environment that own it. It contains no secret.

The connector role gets one extra permission: it can read this one parameter. It cannot read other parameters, and it cannot change the lock.

The wizard fills in the two values the lock needs: TenantId and FlowstateStage in CloudFormation, tenant_id and flowstate_stage in OpenTofu. Do not change them.

When a deploy is refused

If the parameter already exists, the deploy stops before it creates the role:

CloudFormation: the stack fails with AlreadyExists on the resource APNCatalogLock and rolls back.
OpenTofu: tofu apply fails with ParameterAlreadyExists on aws_ssm_parameter.catalog_lock.

This means that another connector already owns the catalog. To see which one, open Systems Manager → Parameter Store in us-east-1 and read the parameter value.

To move the catalog to a different FlowState tenant:

In the FlowState tenant that owns the catalog now, go to Settings → Integrations → APN and click Disconnect.
Delete that connector stack (tofu destroy, or delete the CloudFormation stack). This also deletes the lock.
In the new tenant, run the setup wizard again.

Warning

Do not delete the parameter by hand while the old connector is still deployed. The old tenant keeps its access through the role, and FlowState still refuses the new connection until the old stack is gone.

Deploying the same stack again (for example, to update the connector) does not trip the lock. Only the value of the parameter is refreshed.

What FlowState checks

When you click Test connection in the wizard (or run enable_apn_integration or test_apn_connection over MCP), FlowState reads the lock with your connector role. It refuses the connection in these cases:

Error code	Meaning	What to do
`APN_CATALOG_LOCK_MISSING`	There is no lock parameter in us-east-1. The connector is older than the lock, is in another Region, or was built by hand.	Update the connector. For a role built by hand, see Manual connectors.
`APN_CATALOG_LOCK_UNREADABLE`	The role cannot read the lock. The connector is older than the lock.	Update the connector.
`APN_CATALOG_LOCK_INVALID`	The parameter is not a FlowState lock, or it names a different catalog.	Delete the connector stack and deploy the current connector.
`APN_CATALOG_LOCKED_BY_OTHER_STAGE`	The catalog belongs to a different FlowState environment.	Follow the steps under When a deploy is refused.
`APN_CATALOG_LOCKED_BY_OTHER_TENANT`	The catalog belongs to a different FlowState tenant.	Follow the steps under When a deploy is refused.

FlowState does not show you which other tenant holds the lock. Read the parameter in your own account to find out.

Manual (IAM console) connectors

The Manual tab of the wizard shows the catalog lock as the first resource to create, with its name and value. Create it before the role, as the tab shows.

A role that you built by hand with an older version of the Manual tab has no catalog lock, so Test connection fails with APN_CATALOG_LOCK_MISSING. To fix it, open the Manual tab and create what is missing: the catalog lock, the inline policy ReadCatalogLock on your role, the event-forwarding role and the EventBridge rule. If your role has a different name than the tab shows, create the role with the name from the tab, then disconnect and reconnect with its ARN, and delete your old role.