Help Center/ Resource Access Manager/ API Reference/ APIs/ Associated Principals and Resources/ Associating Principals and Resources
Updated on 2025-10-30 GMT+08:00
View PDF

Associating Principals and Resources

Function

This API is used to associate a list of specified principals or resources with a resource share. If a resource is associated, the principals that have the permission to access the resource share will gain the permission to access that resource in the resource share. If a principal is associated, the principal will have the permission to access the shared resources in the resource share.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    ram:resourceShares:associate

    Write

    resourceShare *

    • g:ResourceTag/<tag-key>

    • ram:AllowExternalPrincipals

    -

    -

    -

    • ram:RequestedResourceType

    • ram:ResourceUrn

    • ram:Principal

    • ram:TargetOrgPaths

URI

POST /v1/resource-shares/{resource_share_id}/associate

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

resource_share_id

Yes

String

ID of the resource share.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Security-Token

No

String

Security token (session token) for temporary security credentials. This parameter is mandatory when you make an API call using temporary security credentials.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

principals

No

Array of strings

List of one or more principals associated with the resource share.

resource_urns

No

Array of strings

List of URNs of one or more resources associated with the resource share.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

resource_share_associations

Array of ResourceShareAssociation objects

Details about the principals or resources associated with a resource share.
Table 5 ResourceShareAssociation

Parameter

Type

Description

associated_entity

String

Associated entity. It can be the resource URN, account ID, URN of the root OU, or URN of another OU.

association_type

String

Entity type in the association.

created_at

String

Time when the association was created.

updated_at

String

Time when the association was last updated.

external

Boolean

Whether the principle is in the same organization as the resource owner.

resource_share_id

String

ID of the resource share.

resource_share_name

String

Name of the resource share.

status

String

Status of the association.

status_message

String

Description of the status to the association.

Example Requests

Associating a list of specified principals or resources with a resource share

POST /v1/resource-shares/{resource_share_id}/associate

{
  "principals" : [ "string" ],
  "resource_urns" : [ "string" ]
}

Example Responses

Status code: 200

Request succeeded.

{
  "resource_share_associations" : [ {
    "associated_entity" : "string",
    "association_type" : "string",
    "created_at" : "2022-08-22T11:50:25.639Z",
    "updated_at" : "2022-08-22T11:50:25.639Z",
    "external" : true,
    "resource_share_id" : "string",
    "resource_share_name" : "string",
    "status" : "string",
    "status_message" : "string"
  } ]
}

Status Codes

Status Code

Description

200

Request succeeded.

Error Codes

See Error Codes.