Sharing a registry across accounts with AWS RAM

You can share an AWS Agent Registry registry with other AWS accounts using AWS Resource Access Manager (RAM). With RAM sharing, accounts outside your own can discover, publish to, or administer records in your registry—without owning the registry itself.

When you share a registry, RAM creates and manages a resource-based policy on your behalf. You choose a managed permission that controls which actions the consumer account can perform, and RAM handles the rest.

How cross-account sharing works

Cross-account sharing follows a three-step process:

Key characteristics:

Prerequisites

Before you share a registry, make sure you meet the following requirements:

In the registry owner account:

In the consumer account:

For organization-internal sharing:

RAM managed permissions for AWS Agent Registry

When you share a registry, you attach an AWS RAM managed permission that controls which actions the consumer account can perform. AWS Agent Registry provides four managed permissions: one default and three role-based. These let you grant the minimum access needed for each use case.

AWSRAMDefaultPermissionAgentRegistryReadOnly

This is the default permission for the agent-registry:Registry resource type. When you create a resource share without specifying a permission, RAM attaches this permission automatically. It grants read-only access to registry metadata and records—both control-plane reads and data-plane discovery—but does not allow publishing records or invoking the registry’s Model Context Protocol (MCP) endpoint.

Use case: Share a registry for visibility and auditing. The consumer can browse and search the catalog, but cannot publish, modify, or invoke tools through the MCP endpoint.

Permissions granted:

AWSRAMPermissionAgentRegistryForConsumer

This permission grants data-plane discovery access plus the ability to invoke the registry’s MCP endpoint. Use this permission for the consumer persona—AI agents or human users who need to discover and use tools registered in the catalog.

Use case: Share a registry with an account whose agents need to discover tools and invoke them through the MCP endpoint. The consumer cannot create or manage records.

Permissions granted:

AWSRAMPermissionAgentRegistryForPublisher

This permission grants everything the Consumer permission grants, plus control-plane access to create, update, delete, and submit records for approval. Use this permission for the publisher persona—builders in a shared account who contribute resources to a centrally owned registry.

Use case: Share a registry with a team that needs to publish MCP servers, agents, or tools into your catalog. The publisher can manage their own records and discover others, but cannot approve or reject records.

Permissions granted:

AWSRAMPermissionAgentRegistryForAdmin

This permission grants everything the Publisher permission grants, plus the ability to approve, reject, or deprecate records. Use this permission for the admin persona—a delegated administrator in another account who curates the shared registry on behalf of the owner.

Use case: Share a registry with an account that manages the full record lifecycle—publishing, reviewing, and approving records—without owning the registry infrastructure itself. The admin cannot update or delete the registry.

Permissions granted:

Choosing a managed permission

Creating a customer-managed permission

For advanced use cases—such as restricting access to only records created by a specific account using condition keys—you can create a customer-managed RAM permission. Customer-managed permissions let you define custom Condition blocks that reference AWS Agent Registry condition keys.

For more information about creating customer-managed permissions, see Shareable resources in the AWS RAM User Guide.

For the condition keys available for AWS Agent Registry, see Condition keys for fine-grained record access.

Share a registry with another account

Only the registry owner can initiate sharing.

Console

The Registry sharing table shows the association. For external shares, the Association status shows Associating until the consumer accepts the invitation.

AWS CLI

Use the create-resource-share command to create a RAM resource share with the registry ARN and the consumer account ID:

aws ram create-resource-share \
  --name "my-registry-share" \
  --resource-arns "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --principals "444455556666" \
  --permission-arns "arn:aws:ram::aws:permission/AWSRAMPermissionAgentRegistryForConsumer" \
  --allow-external-principals

Replace the following:

Verify the share is active:

aws ram get-resource-share-associations \
  --association-type RESOURCE \
  --resource-arns "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId"

Accept a sharing invitation

When a registry is shared with an account outside the owner’s AWS Organization, the consumer account receives an invitation. The consumer must accept the invitation before they can access the shared registry.

Console

After you accept, the shared registry appears in the consumer’s registry list. You can also choose View invitation details to see the share in the AWS RAM console.

AWS CLI

Find the pending invitation:

aws ram get-resource-share-invitations \
  --query 'resourceShareInvitations[?status==`PENDING`]'

Accept the invitation using the invitation ARN from the response:

aws ram accept-resource-share-invitation \
  --resource-share-invitation-arn "arn:aws:ram:us-east-1:111122223333:resource-share-invitation/12345678-abcd-efgh-ijkl-123456789012"

Reject a sharing invitation

If you do not want to access a shared registry, you can reject the invitation. Rejecting an invitation means you will not have access to the shared registry.

Console

AWS CLI

Find the pending invitation:

aws ram get-resource-share-invitations \
  --query 'resourceShareInvitations[?status==`PENDING`]'

Reject the invitation:

aws ram reject-resource-share-invitation \
  --resource-share-invitation-arn "arn:aws:ram:us-east-1:111122223333:resource-share-invitation/12345678-abcd-efgh-ijkl-123456789012"

Access a shared registry

After the share is active (either through accepting an invitation or automatic organization-level acceptance), the consumer calls AWS Agent Registry APIs using their own credentials against the owner’s registry ARN. The specific operations available depend on the managed permission attached to the share.

Example: Discover records as a consumer

# List approved records in the shared registry
aws agent-registry list-discoverable-registry-records \
  --registry-id "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId"

# Search for tools
aws agent-registry search-discoverable-registry-records \
  --registry-ids "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --search-query "order management"

# Get full record details
aws agent-registry batch-get-discoverable-registry-record \
  --entries '[{"registryId":"arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId","recordIds":["arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId/record/MyRecordId"]}]'

Example: Publish a record as a publisher

aws agent-registry-control create-registry-record \
  --registry-id "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --name "my-mcp-server" \
  --display-name "Order Management MCP Server" \
  --record-type MCP \
  --descriptors '{"mcpServer": {"data": "{\"name\": \"order-mgmt\", \"description\": \"Order management tools\", \"version\": \"1.0.0\"}", "dataSchemaVersion": "2025-12-11"}}' \
  --record-version "1.0"

Stop sharing with an account

To revoke a consumer’s access to your shared registry, remove the consumer account from the resource share.

Console

The consumer immediately loses access to the registry. There might be a short propagation delay (up to 30 seconds) before access is fully revoked.

AWS CLI

Use disassociate-resource-share to remove a consumer account from the share:

aws ram disassociate-resource-share \
  --resource-share-arn "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012" \
  --principals "444455556666"

Verify the principal is disassociated:

aws ram get-resource-share-associations \
  --association-type PRINCIPAL \
  --resource-share-arns "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012"

To delete the entire resource share (removing all consumer accounts at once):

aws ram delete-resource-share \
  --resource-share-arn "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012"

Condition keys for fine-grained record access

AWS Agent Registry provides two service-specific condition keys. You can use these keys in customer-managed RAM permissions, IAM identity policies, and SCPs to control access at the individual record level. They are especially useful when sharing a registry across accounts, where you want a consumer account to act only on the records it owns or that originate from its own account, even though another account owns the registry itself.

Both keys are resolved at authorization time from the stored record and cannot be set from request input, so a consumer cannot spoof them to gain access to records that belong to other accounts.

Registry record condition keys

The following condition keys apply to the record-level operations listed in the API operations column.

If you need to keep records from other accounts entirely out of a consumer’s view, do not grant the search and list actions in the shared permission.

Example: Restrict access to records the consumer created

The following customer-managed RAM permission allows a consumer to read, update, and delete only records where the creator account matches the consumer’s own account:

{
  "Effect": "Allow",
  "Action": [
    "agent-registry:GetDiscoverableRegistryRecord",
    "agent-registry:GetRegistryRecord",
    "agent-registry:UpdateRegistryRecord",
    "agent-registry:DeleteRegistryRecord"
  ],
  "Condition": {
    "StringEquals": {
      "agent-registry:RecordCreatorAccount": "${aws:PrincipalAccount}"
    }
  }
}

The ${aws:PrincipalAccount} policy variable resolves dynamically at evaluation time—each consumer can only access records they themselves created, even within a shared registry.

Example: Restrict access to records that originate from the consumer’s account

The following customer-managed RAM permission allows a consumer to read only records whose source resource resides in the consumer’s own account—useful when records are auto-detected from resources owned by the consumer:

{
  "Effect": "Allow",
  "Action": [
    "agent-registry:GetDiscoverableRegistryRecord",
    "agent-registry:GetRegistryRecord"
  ],
  "Condition": {
    "StringEquals": {
      "agent-registry:RecordSourceAccount": "${aws:PrincipalAccount}"
    }
  }
}

For instructions on creating a customer-managed RAM permission, see Creating a customer-managed permission in the AWS RAM User Guide.

Troubleshooting