---
title: "Sub Account 개요"
slug: "management-subaccount"
tags: ["Sub Account", "overview"]
updated: 2026-09-17T09:16:41Z
published: 2026-09-17T09:16:41Z
canonical: "api.ncloud-docs.com/management-subaccount"
---

> ## 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.

# Sub Account 개요

Classic/VPC 환경에서 이용 가능합니다.

Sub Account는 여러 사용자가 같은 리소스를 이용하고 관리할 수 있는 서브 계정을 제공하는 네이버 클라우드 플랫폼의 서비스입니다. Sub Account 서비스에서는 서브 계정, 그룹, 정책, 역할, External Access 기능에 대한 API를 RESTful 형태로 제공합니다.

## Sub Account 공통 설정

Sub Account API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.

### 요청

공통 요청 형식을 설명합니다.

#### API URL

요청 API URL은 다음과 같습니다.

```
서브 계정, 그룹, 정책, 역할: https://subaccount.apigw.ntruss.com
외부 접근 권한: https://externalaccess.apigw.ntruss.com
```

#### 요청 헤더

헤더에 대한 설명은 다음과 같습니다.

| 필드 | 필수 여부 | 설명 |
| --- | --- | --- |
| `x-ncp-apigw-timestamp` | Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초) - API Gateway 서버와 5분 이상 시간 차 발생 시 유효하지 않은 요청으로 간주 - Unix Timestamp 형식 |
| `x-ncp-iam-access-key` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key - Access Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi) 참조 - 서브 계정의 Access Key 발급 및 확인: [서브 계정 생성](https://guide.ncloud-docs.com/docs/subaccount-use#%EC%84%9C%EB%B8%8C-%EA%B3%84%EC%A0%95-%EC%83%9D%EC%84%B1) 참조 |
| `x-ncp-apigw-signature-v2` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - Secret Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi) 참조 - 서명 생성: [시그니처 생성](/docs/common-ncpapi) 참조 |
| `Accept` | Optional | 응답 데이터의 형식 - `application/json` |
| `Content-type` | Optional | 요청 데이터의 형식 - `application/json` |

### 응답

공통 응답 형식을 설명합니다.

#### 응답 데이터 타입

공통 응답 데이터 타입을 설명합니다.

**ProcessResult** ProcessResult는 API 처리 결과를 정의합니다. ProcessResult에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `success` | Boolean | Required | API 처리 결과 - `true` \| `false` - `true`: 성공 - `false`: 실패 |
| `id` | String | Optional | 생성/수정 결과 아이디 - 생성, 다중 추가/삭제 API에서 사용 |
| `message` | String | Optional | API 처리 결과 메시지 |

ProcessResult의 구문과 응답 예시는 다음과 같습니다.

- 구문

```
ProcessResult {
  Boolean success;
  String id;
  String message;
}
```
- 예시

```
{
  "id": "",
  "success": true
}
```

**ErrorResponse** ErrorResponse는 API 호출 실패 시 실패에 대한 내용을 정의합니다. ErrorResponse에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| errorCode | Integer | Required | Required |
| message | String | Required | String |

ErrorResponse의 구문과 예시는 다음과 같습니다.

- 구문

```
ErrorResponse {
  int errorCode;
  String message;
}
```
- 예시

```
{
  "errorCode": 9011,
  "message": "이미 존재하는 역할명입니다."
}
```

#### 응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
| --- | --- | --- | --- |
| 200 | - | 최대 허용값을 초과하였습니다. | 최대 허용값 초과 |
| 400 | 120 | 중복된 ID입니다. 다른 ID를 입력해 주세요. | 중복된 아이디 입력 |
| 400 | 30 | 잘못된 subAccountId입니다. | 존재하지 않는 서브 계정 아이디 입력 |
| 400 | 30 | 잘못된 groupNo 입니다. | 존재하지 않는 그룹 아이디 입력 |
| 400 | 400 | Request format is not json | 입력 값 형식 오류 |
| 400 | 400 | sessionExpirationDays is required, Request format is not json | 파라미터 입력 오류 |
| 400 | 400 | 접근 제한 IP 대역 수는 최대 100개 입니다. | 가능한 IP 대역 수 초과 - 콘솔 접근 제한 IP 대역 수는 최대 100개 |
| 400 | 400 | 역할 명을 입력 해 주세요 : [roleName] | 역할 이름 누락 - 3~100자로 입력 |
| 400 | 400 | 역할 명은 3~100자 사이로 입력 해 주세요. : [roleName] | 역할 이름 글자 수 오류 |
| 400 | 400 | 역할 타입을 지정 해 주세요 : [roleType] | 역할 타입 입력 오류 - 역할 타입 지정 |
| 400 | 400 | 역할 타입이 잘못 되었습니다. | 역할 타입 입력 오류 - 허용된 역할 타입 지정 |
| 400 | 400 | isMyAccount가 누락 되었습니다. : [isMyAccount] | `isMyAccount` 파라미터 누락 |
| 400 | 9001 | 계정이름을 입력해주세요. | 계정 이름 누락 또는 오류 |
| 400 | 9001 | 로그인ID를 입력해주세요. | 로그인 아이디 입력 필요 |
| 400 | 9002 | 역할 타입이 Server일 때 미사용 세션 만료 시간은 허용되지 않습니다. | 파라미터 입력 오류 - 세션 만료 시간을 지정할 수 없는 역할 타입 |
| 400 | 9002 | 세션 만료 시간은 [600, 1800, 3600, 10800] 초 만 설정할 수 있습니다. | 세션 만료 시간 입력 오류 |
| 400 | 9010 | 문자, 숫자, 특수 문자 ., _, -를 허용하며, 문자로 시작하는 문자열을 3자~100자 이내로 입력해 주십시오. | 입력값 오류 - 3~100자로 영문자, 숫자, 특수문자 사용 |
| 400 | 9010 | 영문 소문자, 숫자를 허용하며, 3자~20자 이내로 입력해 주십시오. | URL 형식 오류 - 3~20자로 영문 소문자, 숫자 허용 |
| 400 | 9011 | 이미 존재하는 역할명입니다. | 이미 사용 중인 역할 이름 입력 |
| 400 | 9015 | 안전하지 않은 비밀번호입니다. | 사용할 수 없는 비밀번호 입력 |
| 400 | 904 | 유효하지 않은 API Key입니다. | 존재하지 않는 Access Key 입력 |
| 401 | 30 | 잘못된 subAccountId입니다. | 존재하지 않는 서브 계정 아이디 입력 |
| 404 | 30 | 잘못된 idNo입니다. | 존재하지 않는 서브 계정 아이디 입력 |
| 404 | 30 | 잘못된 roleNo입니다. | 존재하지 않는 역할 아이디 입력 |
| 404 | 404 | 등록되지 않은 정책입니다. | 존재하지 않는 정책 아이디 입력 |
| 404 | 910 | 역할에 맞지 않는 엔티티가 있습니다. | 역할 유형에 맞지 않는 적용 대상 존재 |
| 409 | 9012 | 대상 Role에 등록 가능한 엔티티 갯수를 초과하였습니다. | 역할 적용 대상의 허용 개수 초과 |
| 409 | 9012 | 최대 허용값을 초과하였습니다. | 최대 허용값 초과 |
| 500 | 500 | Internal Server Error | 내부 서버 오류 |

참고

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/common-ncpapi#3%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

## Sub Account API

Sub Account 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.

### 서브 계정

서브 계정 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [서브 계정 목록 조회](/docs/management-subaccount-getsubaccounts) | 서브 계정 목록 조회 |
| [서브 계정 조회](/docs/management-subaccount-getsubaccount) | 서브 계정 단건 상세 조회 |
| [서브 계정 생성](/docs/management-subaccount-createsubaccount) | 서브 계정 생성 |
| [서브 계정 수정](/docs/management-subaccount-putsubaccount) | 서브 계정 정보 수정 |
| [서브 계정 삭제](/docs/management-subaccount-deletesubaccount) | 서브 계정 삭제 |
| [Access Key 조회](/docs/management-subaccount-getaccesskey) | 서브 계정 Access Key 조회 |
| [Access Key 생성](/docs/management-subaccount-createaccesskey) | 서브 계정 Access Key 생성 |
| [Access Key 삭제](/docs/management-subaccount-deletekey) | 서브 계정 Access Key 삭제 |
| [Access Key 상태 설정](/docs/management-subaccount-suspendkey) | 서브 계정 Access Key 활성화 또는 비활성화 설정 |
| [로그인 접속키 조회](/docs/management-subaccount-getloginalias) | 서브 계정 로그인 주소에 사용되는 로그인 접속키 조회 |
| [로그인 접속키 설정](/docs/management-subaccount-putloginalias) | 서브 계정 로그인 주소에 사용되는 로그인 접속키 설정 |
| [로그인 아이디 체크](/docs/management-subaccount-checkloginid) | 서브 계정 로그인 아이디 유효성 및 중복 여부 확인 |
| [로그인 비밀번호 체크](/docs/management-subaccount-checkpassword) | 서브 계정 로그인 비밀번호 유효성 및 복잡도 확인 |
| [유휴 세션 만료 시간 조회](/docs/management-subaccount-getsessionexpirationtime) | 서브 계정 유휴 세션 만료 시간 조회 |
| [유휴 세션 만료 시간 설정](/docs/management-subaccount-postsessionexpirationtime) | 서브 계정 유휴 세션 만료 시간 설정 |
| [로그인 비밀번호 만료일 조회](/docs/management-subaccount-getpasswordexpirationdays) | 서브 계정 로그인 비밀번호 만료일(변경 주기) 조회 |
| [로그인 비밀번호 만료일 설정](/docs/management-subaccount-postpasswordexpirationdays) | 서브 계정 로그인 비밀번호 만료일(변경 주기) 설정 |
| [로그인 비밀번호 재설정](/docs/management-subaccount-putpassword) | 서브 계정 로그인 비밀번호 수정 |
| [정책 할당](/docs/management-subaccount-attachpolicytosubaccount) | 서브 계정에 정책 할당 |
| [정책 삭제](/docs/management-subaccount-detachpolicyfromsubaccount) | 서브 계정에 할당된 정책 삭제 |
| [그룹 추가](/docs/management-subaccount-addsubaccounttogroup) | 서브 계정을 그룹에 추가 |
| [그룹 삭제](/docs/management-subaccount-deletesubaccountfromgroup) | 서브 계정을 그룹에서 삭제 |
| [콘솔 접근 규칙 조회](/docs/management-subaccount-getaccessrule) | 서브 계정 콘솔 접근 규칙 조회 |
| [콘솔 접근 규칙 수정](/docs/management-subaccount-putaccessrule) | 서브 계정 콘솔 접근 규칙 수정 |
| [API 접근 규칙 조회](/docs/management-subaccount-getapiaccessrule) | 서브 계정 API 접근 규칙 조회 |
| [API 접근 규칙 수정](/docs/management-subaccount-putapiaccessrule) | 서브 계정 API 접근 규칙 수정 |
| [2차 인증 정보 조회](/docs/management-subaccount-2factorauthentication) | 서브 계정 2차 인증 정보 조회 |
| [태그 조회](/docs/management-subaccount-gettag) | 서브 계정에 추가된 태그 조회 |
| [태그 추가](/docs/management-subaccount-addtag) | 서브 계정에 태그 추가 |
| [태그 삭제](/docs/management-subaccount-removetag) | 서브 계정에 추가된 태그 삭제 |
| [사용자 정보 조회](/docs/management-subaccount-getuserdetail) | 권한이 부여된 서브 계정 사용자 정보 조회 |
| [사용자 아이디 조회](/docs/management-subaccount-getsubaccountidno) | 서브 계정 아이디 조회 |

### 그룹

그룹 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [그룹 목록 조회](/docs/management-subaccount-getgroups) | 그룹 목록 조회 |
| [그룹 조회](/docs/management-subaccount-getgroup) | 그룹 단건 상세 조회 |
| [그룹 생성](/docs/management-subaccount-creategroup) | 그룹 생성 |
| [그룹 수정](/docs/management-subaccount-putgroup) | 그룹 정보 수정 |
| [그룹 삭제](/docs/management-subaccount-deletegroup) | 그룹 삭제 |
| [서브 계정 추가](/docs/management-subaccount-attachsubaccounttogroup) | 그룹에 서브 계정 추가 |
| [서브 계정 삭제](/docs/management-subaccount-detachsubaccountfromgroup) | 그룹에서 서브 계정 삭제 |
| [정책 할당](/docs/management-subaccount-attachpolicytogroup) | 그룹에 정책 할당 |
| [정책 삭제](/docs/management-subaccount-detachpolicyfromgroup) | 그룹에 할당된 정책 삭제 |
| [태그 조회](/docs/management-subaccount-getgrouptag) | 그룹에 추가된 태그 조회 |
| [태그 추가](/docs/management-subaccount-addgrouptag) | 그룹에 태그 추가 |
| [태그 삭제](/docs/management-subaccount-removegrouptag) | 그룹에 추가된 태그 삭제 |

### 정책

정책 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [정책 목록 조회](/docs/management-subaccount-getpolicies) | 정책 목록 조회 |
| [정책 조회](/docs/management-subaccount-getpolicy) | 정책 단건 상세 조회 |
| [정책 유효성 확인](/docs/management-subaccount-validatepolicy) | 사용자 정의 정책(User Created) 유효성 확인 |
| [정책 생성](/docs/management-subaccount-createpolicy) | 사용자 정의 정책(User Created) 생성 |
| [정책 수정](/docs/management-subaccount-updatepolicy) | 사용자 정의 정책(User Created) 정보 수정 |
| [정책 목록 삭제](/docs/management-subaccount-deletepolicymulti) | 2개 이상의 사용자 정의 정책(User Created) 일괄 삭제 |
| [정책 삭제](/docs/management-subaccount-deletepolicy) | 사용자 정의 정책(User Created) 삭제 |
| [정책 할당 리소스 조회](/docs/management-subaccount-getpolicyresources) | 정책 할당 리소스(서브 계정, 그룹, 역할) 조회 |
| [태그 조회](/docs/management-subaccount-getpolicytag) | 사용자 정의 정책(User Created)에 추가된 태그 조회 |
| [태그 추가](/docs/management-subaccount-addpolicytag) | 사용자 정의 정책(User Created)에 태그 추가 |
| [태그 삭제](/docs/management-subaccount-removepolicytag) | 사용자 정의 정책(User Created)에 추가된 태그 삭제 |

### 역할

역할 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [역할 목록 조회](/docs/management-subaccount-getroles) | 역할 목록 조회 |
| [역할 조회](/docs/management-subaccount-getrole) | 역할 단건 상세 조회 |
| [역할 생성](/docs/management-subaccount-createrole) | 역할 생성 |
| [역할 수정](/docs/management-subaccount-updaterole) | 역할 정보 수정 |
| [역할 삭제](/docs/management-subaccount-deleterole) | 역할 삭제 |
| [정책 할당](/docs/management-subaccount-attachpolicytorole) | 역할에 정책 할당 |
| [정책 삭제](/docs/management-subaccount-detachpolicyfromrole) | 역할에 할당된 정책 삭제 |
| [역할(Account) 적용 대상 조회](/docs/management-subaccount-gettargetaccount) | Account 역할 적용 대상 조회 |
| [역할(Account) 적용 대상 추가](/docs/management-subaccount-attachentitytorole) | Account 역할 적용 대상 추가 |
| [역할(Account) 적용 대상 삭제](/docs/management-subaccount-detachentityfromrole) | Account 역할 적용 대상 삭제 |
| [역할(Server, Service) 적용 대상 추가](/docs/management-subaccount-attachentitytorole) | Server, Service 역할 적용 대상 추가 |
| [역할(Server, Service) 적용 대상 삭제](/docs/management-subaccount-detachentityfromrole) | Server, Service 역할 적용 대상 삭제 |
| [역할 목록 상태 설정](/docs/management-subaccount-suspendroles) | 2개 이상의 역할 활성화 또는 비활성화 일괄 설정 |
| [역할 상태 설정](/docs/management-subaccount-suspendrole) | 역할 활성화 또는 비활성화 설정 |
| [태그 조회](/docs/management-subaccount-getroletag) | 역할에 추가된 태그 조회 |
| [태그 추가](/docs/management-subaccount-addroletag) | 역할에 태그 추가 |
| [태그 삭제](/docs/management-subaccount-removeroletag) | 역할에 추가된 태그 삭제 |
| [전환 가능 역할 조회](/docs/management-subaccount-switchablerole-get) | 서브 계정에서 전환 가능한 역할 조회 |
| [전환 가능 역할 등록](/docs/management-subaccount-switchablerole-post) | 서브 계정에서 전환 가능한 역할 등록 |
| [전환 가능 역할 수정](/docs/management-subaccount-switchablerole-put) | 서브 계정에서 전환 가능한 역할 정보 수정 |
| [전환 가능 역할 삭제](/docs/management-subaccount-switchablerole-delete) | 서브 계정에서 전환 가능한 역할 삭제 |

### External Access

External Access 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [Trust Anchor 목록 조회](/docs/management-subaccount-gettrustanchorlist) | Trust Anchor 목록 조회 |
| [Trust Anchor 조회](/docs/management-subaccount-gettrustanchors) | Trust Anchor 단건 상세 조회 |
| [Trust Anchor 생성](/docs/management-subaccount-posttrustanchors) | Trust Anchor 생성 |
| [Trust Anchor 수정](/docs/management-subaccount-patchtrustanchors) | Trust Anchor 정보 수정 |
| [Trust Anchor 활성화](/docs/management-subaccount-enabletrustanchors) | Trust Anchor 상태 활성화 설정 |
| [Trust Anchor 비활성화](/docs/management-subaccount-disabletrustanchors) | Trust Anchor 상태 비활성화 설정 |
| [Trust Anchor 삭제](/docs/management-subaccount-deletetrustanchors) | Trust Anchor 삭제 |
| [Profile 목록 조회](/docs/management-subaccount-getprofilelist) | Profile 목록 조회 |
| [Profile 조회](/docs/management-subaccount-getprofiles) | Profile 단건 상세 조회 |
| [Profile 생성](/docs/management-subaccount-postprofiles) | Profile 생성 |
| [Profile 수정](/docs/management-subaccount-patchprofiles) | Profile 정보 수정 |
| [Profile 활성화](/docs/management-subaccount-enableprofiles) | Profile 상태 활성화 설정 |
| [Profile 비활성화](/docs/management-subaccount-disableprofiles) | Profile 상태 비활성화 설정 |
| [Profile 삭제](/docs/management-subaccount-deleteprofiles) | Profile 삭제 |
| [Subject 목록 조회](/docs/management-subaccount-getsubjectlist) | Subject 목록 조회 |
| [Subject 조회](/docs/management-subaccount-getsubjects) | Subject 단건 상세 조회 |
| [Subject Activity 목록 조회](/docs/management-subaccount-getcredentiallist) | Subject Activity 목록(동일 Subject를 가진 인증서 상세 사용 이력) 조회 |
| [CRL 목록 조회](/docs/management-subaccount-getcrllist) | CRL(인증서 폐기 목록) 목록 조회 |
| [CRL 조회](/docs/management-subaccount-getcrls) | CRL(인증서 폐기 목록) 단건 상세 조회 |
| [CRL 생성](/docs/management-subaccount-postcrls) | CRL(인증서 폐기 목록) 생성 |
| [CRL 수정](/docs/management-subaccount-patchcrls) | CRL(인증서 폐기 목록) 정보 수정 |
| [CRL 활성화](/docs/management-subaccount-enablecrls) | CRL(인증서 폐기 목록) 상태 활성화 설정 |
| [CRL 비활성화](/docs/management-subaccount-disablecrls) | CRL(인증서 폐기 목록) 상태 비활성화 설정 |
| [CRL 삭제](/docs/management-subaccount-deletecrls) | CRL(인증서 폐기 목록) 삭제 |

## Sub Account 연관 리소스

Sub Account API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.

- Sub Account API 사용 방법
  - [서명(시그니처) 생성](/docs/common-ncpapi): 요청 헤더에 추가할 서명 생성 방법
  - [API Gateway 사용 가이드](https://guide.ncloud-docs.com/docs/apigw-apigw-1): 요청 헤더에 추가할 API Key 발급
  - [Ncloud 공통 응답 상태 코드](/docs/common-ncpapi#3-%EC%9D%91%EB%8B%B5-%EC%83%81%ED%83%9C-%EC%BD%94%EB%93%9C): Sub Account 서비스에서 사용하는 네이버 클라우드 플랫폼의 공통 응답 상태 코드 정보
- Sub Account 서비스 사용 방법
  - [Sub Account 사용 가이드](https://guide.ncloud-docs.com/docs/subaccount-overview): 네이버 클라우드 플랫폼 콘솔에서 Sub Account 사용하는 방법
  - [Ncloud 사용 환경 가이드](https://guide.ncloud-docs.com/docs/environment-environment-1-1): VPC, Classic 환경 및 지원 여부에 대한 가이드
  - [요금 소개, 특징, 상세 기능](https://www.ncloud.com/product/management/subAccount): Sub Account의 요금 체계, 특징, 상세 기능 요약
  - [서비스 최신 소식](https://www.ncloud.com/intro/news): Sub Account 서비스 관련 최신 소식
  - [자주 하는 질문](https://www.ncloud.com/support/faq/prod?categoryCode2=MGMT&categoryCode3=SV_0078&page=1): Sub Account 서비스 사용자들이 자주 하는 질문
  - [문의하기](https://www.ncloud.com/support/question/general): API 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의