---
title: "Create role"
slug: "management-subaccount-createrole"
tags: ["Sub Account"]
updated: 2026-09-17T10:05:32Z
published: 2026-09-17T10:05:32Z
canonical: "api.ncloud-docs.com/management-subaccount-createrole"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create role

Available in Classic and VPC

Create a role. Roles are temporary credentials composed of policies, and you can create roles to grant permissions to resources such as servers as well as sub accounts.

              Note

              

In the Sub Account API, you can create and manage server, account, and service roles. The creation, configuration, and deletion of single sign-on roles can be done in the Ncloud Single Sign-On service.

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| POST | /api/v1/roles |

### Request headers

For information about the headers common to all Sub Account APIs, see [Sub Account request headers](/docs/en/management-subaccount#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request body

You can include the following data in the body of your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `descCont` | String | Optional | Description of the role (byte) - 0-300 |
| `roleName` | String | Required | Role name - Enter 3-100 characters by combining Korean letters, lowercase/uppercase English letters, numbers, Japanese letters, and special characters "-", "_", and ".". - First letter must be a Korean letter, lowercase/uppercase English letter, or Japanese letter. |
| `roleType` | String | Required | Role type - `Server` \| `Account` \| `Service` - `Server`: It is assigned to the server resource in the VPC environment. You can access services and resources without an access key. - `Account`: Assign portal and console access permissions for the main account to the sub account. Role switching allows access to the target account's resources. - `Service`: It is assigned to the service. You can access resources of other services. |
| `sessionExpirationSec` | Integer | Conditional | Session expiration time (second) - `600` \| `1800` \| `3600` \| `10800` - Required if `roleType` is `Account` |
| `tags` | Map | Optional | Role's tag - Up to 20 per resource. - See [Key and value restrictions](/docs/en/management-resourcemanager-attachtag). |

### Request example

The request example is as follows:

```
curl --location --request POST 'https://subaccount.apigw.ntruss.com/api/v1/roles' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
	"descCont": "Role description",
	"roleName": "role000",
	"roleType": "Account",
	"sessionExpirationSec": 600,
    "tags": {
        "env": "dev",
        "team": "a"
    }
}'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | Boolean | - | API call success status - `true` \| `false` - `true`: Succeeded - `false`: Failed |
| `id` | String | - | Role ID |

### Response status codes

For information about the HTTP status codes common to all Sub Account APIs, see [Sub Account status codes](/docs/en/management-subaccount#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The response example is as follows:

```
{
    "success": true,
    "id": "5befa3a0-****-****-****-246e96591a38"
}
```