Help Center/ SecMaster/ API Reference/ SecMaster APIs (Excluding APIs for Security Analysis V2)/ Agency Management/ Creating an Agency and Granting Permissions to It
Updated on 2025-10-29 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating an Agency and Granting Permissions to It

Function

This API is used to create an agency based on the role and scope in the body and assign the policy to the agency.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/agency

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID, which is used to specify the project that a resource belongs to. You can query the resources of a project by project ID. You can obtain the project ID from the API or console. Obtaining the Project ID

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token.

You can call the IAM API to obtain a user token. The value of X-Subject-Token in the response header is the user token.

X-Language

No

String

Language.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

organizations

No

Array of Organization objects

OU list.

role_descriptions

No

Array of Role objects

Role list.
Table 4 Organization

Parameter

Mandatory

Type

Description

account_id

Yes

String

Role ID.

organization_id

Yes

String

Role ID.
Table 5 Role

Parameter

Mandatory

Type

Description

id

Yes

String

Role ID.

display_name

Yes

String

Role name.

role_description

Yes

String

Role description.

description

Yes

String

Description.

scope

Yes

String

Role scope.

Response Parameters

Status code: 201

Request succeeded.

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

code

String

Definition

Error code.

Range

N/A

message

String

Definition

Error description.

Range

N/A

Status code: 500

Table 7 Response body parameters

Parameter

Type

Description

code

String

Definition

Error code.

Range

N/A

message

String

Definition

Error description.

Range

N/A

Example Requests

None

Example Responses

Status code: 403

Insufficient permissions.

{
  "error_code" : "csb.00180005",
  "error_msg" : "Permission iam:agencies:createAgency is required to create an agency."
}

Status code: 500

Internal system error.

{
  "error_code" : "csb.00180001",
  "error_msg" : "System busy. Try again later."
}

Status Codes

Status Code

Description

201

Request succeeded.

403

Insufficient permissions.

500

Internal system error.

Error Codes

See Error Codes.

Parent topic: Agency Management