Creating a Service-linked Agency

Function

This API is used to create a service-linked agency.

Authorization Information

Each account root user has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
iam:agencies:createServiceLinkedAgencyV5	Write	agency *	-	-	-
iam:agencies:createServiceLinkedAgencyV5	Write	-	iam:ServicePrincipal	-	-

URI

PUT /v5/service-linked-agencies

Request Parameters

**Table 1** Request body parameters
Parameter	Mandatory	Type	Description
service_principal	Yes	String	Definition: Service principal Constraints: The value starts with service. and is followed by 1 to 56 characters. Only letters, digits, and hyphens (-) are allowed. Range: N/A Default Value: N/A
description	No	String	Definition: Service-linked agency description Constraints: The value cannot contain the following characters: "@", "#", "%", "&", "<", ">", "\", "$", "^", and "". Range: The value contains 0 to 1,000 characters. Default Value*: N/A

Response Parameters

Status code: 201

**Table 2** Response body parameters
Parameter	Type	Description
agency	agency object	Definition: Agency or trust agency. Range: N/A

**Table 3** agency
Parameter	Type	Description
urn	String	Definition : Uniform Resource Name (URN). For details, see Reference. Range: N/A.
trust_policy	String	Definition: JSON format of the policy document of a trust agency's trust policy. Range: N/A
created_at	String	Definition: Time when the agency or trust agency was created. Range: N/A
description	String	Definition: Description of an agency or trust agency. Range: N/A
max_session_duration	Integer	Definition: Maximum session duration of an agency or trust agency, in seconds. Range: The value ranges from 3,600 to 43,200.
path	String	Definition: Resource path. Range: N/A
agency_id	String	Definition: Agency or trust agency ID. Range: N/A
agency_name	String	Definition: Name of an agency or trust agency. Range: N/A
trust_domain_id	String	Definition: ID of the delegated account. Range: N/A
trust_domain_name	String	Definition: Name of the delegated account. Range: N/A

Status code: 403

**Table 4** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is PAP5.XXXX, for example, PAP5.0012.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.
request_id	String	Definition: Unique identifier of an API request, which is used to locate API calling exceptions. Range: N/A
encoded_authorization_message	String	Definition : Encrypted details returned when the authentication fails, which are used to locate authentication problems. The STS5 decryption API can be used for decryption. For details, see API link. Range: N/A.

Status code: 404

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is PAP5.XXXX, for example, PAP5.0012.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.
request_id	String	Definition: Unique identifier of an API request, which is used to locate API calling exceptions. Range: N/A

Status code: 409

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is PAP5.XXXX, for example, PAP5.0012.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.
request_id	String	Definition: Unique identifier of an API request, which is used to locate API calling exceptions. Range: N/A

Example Requests

Creating a service-linked agency whose service principal is service.xxx

PUT https://{endpoint}/v5/service-linked-agencies

{
  "service_principal" : "service.xxx",
  "description" : "description"
}

Example Responses

Status code: 201

Successful

{
  "agency" : {
    "urn" : "iam::accountid:agency:service-linked-agency/service.xxx/name",
    "trust_policy" : "{\"Version\":\"5.0\",\"Statement\":[{\"Action\":[\"sts:agencies:assume\",\"sts::tagSession\",\"sts::setSourceIdentity\"],\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"service.xxx\"]}}]}",
    "created_at" : "2023-09-11T10:13:25.414Z",
    "description" : "description",
    "max_session_duration" : 3600,
    "path" : "service-linked-agency/service.xxx/",
    "agency_id" : "id",
    "agency_name" : "name",
    "trust_domain_id" : null,
    "trust_domain_name" : null
  }
}