--- title: "Sub Account 개요" slug: "gov-iam-v2-overview" updated: 2026-10-22T10:47:29Z published: 2026-10-22T10:47:29Z canonical: "api-gov.ncloud-docs.com/gov-iam-v2-overview" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Sub Account 개요 이 가이드는 API 명세를 기반으로 자동 생성했습니다. Classic/VPC 환경에서 이용 가능합니다. Ncloud API 표준 규격을 적용한 API입니다. Sub Account는 여러 사용자가 같은 리소스를 이용하고 관리할 수 있는 서브 계정을 제공하는 네이버 클라우드 플랫폼의 서비스입니다. Sub Account 서비스에서는 서브 계정, 그룹, 정책, 역할 기능에 대한 API를 RESTful 형태로 제공합니다. 참고 API의 가독성을 높이기 위해 Sub Account API의 v1 버전을 ncloud에서 정의한 표준 표현에 의거하여 v2 버전으로 새롭게 출시하였습니다. ## Sub Account 요청 형식 Sub Account API에서 공통으로 사용하는 요청 형식을 설명합니다. ### API URL 요청 API URL은 다음과 같습니다. ``` https://subaccount.apigw.gov-ntruss.com/api/v2 ``` ### 요청 헤더 요청 헤더에 대한 설명은 다음과 같습니다. | 필드 | 필수 여부 | 설명 | | --- | --- | --- | | `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/api-call-std-auth#api-%EC%9D%B8%EC%A6%9D%ED%82%A4-%EC%83%9D%EC%84%B1) 참조 | | `x-ncp-apigw-signature-v2` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - 서명 생성: [시그니처 생성](/docs/api-call-std-auth#%EC%8B%9C%EA%B7%B8%EB%8B%88%EC%B2%98-%EC%83%9D%EC%84%B1) 참조 | ## Sub Account 응답 형식 Sub Account API에서 공통으로 사용하는 응답 형식을 설명합니다. ### 응답 바디 API 오류 시 공통으로 반환하는 응답 바디는 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `error` | Object | - | 에러 상세 정보 | | `error.errorCode` | String | - | 표준 NCP Error Code - <예시> Unauthorized | | `error.message` | String | - | 에러 설명 메시지 - <예시> Invalid authentication credentials. | | `error.detail` | String | - | 에러 상세 원인. 원인이 된 자원 식별자 등 상세 원인이 있을 때만 포함 - <예시> Policy does not Exist. (policyId: 4e066e50-9c3a-11e7-8a66-1e5021fa7c80) | | `error.fieldErrors` | List | - | 요청 본문 검증에 실패한 필드 목록. 400 Bad Request에서 검증 실패가 여러 건이면 전량 포함되며, 그 외 에러 응답에는 포함되지 않음 | | `error.fieldErrors[].field` | String | - | 실패한 필드의 경로. 배열 요소는 인덱스로 표기 - <예시> permissions[0].actions[1] | | `error.fieldErrors[].message` | String | - | 실패 사유 메시지 - <예시> The specified action is invalid. | 동기 방식 배치 API는 오류를 `error`와 `failures` 두 가지 중 하나의 형태로 응답합니다. 요청 항목과 무관한 오류(인증·권한, 요청 형식, 서버 내부 오류 등)는 `error`로, 요청 항목의 처리에서 발생한 실패는 `failures`로 반환합니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `failures` | Map | - | 실패 목록. 키는 요청 배열의 순서 인덱스이며, 실패가 발생한 항목만 포함 - <예시> `{"1": {"errorCode": "NotFound", "message": "One or more of the resources in the request does not exist in the system.", "detail": "Policy does not Exist. (policyId: 4e066e50-9c3a-11e7-8a66-1e5021fa7c80)"}}` | | `failures.{index}` | Object | - | 실패 항목의 에러 정보 | | `failures.{index}.errorCode` | String | - | 표준 NCP Error Code - <예시> NotFound | | `failures.{index}.message` | String | - | 에러 설명 메시지 - <예시> One or more of the resources in the request does not exist in the system. | | `failures.{index}.detail` | String | - | 에러 상세 원인. 원인이 된 자원 식별자를 포함 - <예시> Policy does not Exist. (policyId: 4e066e50-9c3a-11e7-8a66-1e5021fa7c80) | ### 응답 상태 코드 응답 상태 코드에 대한 설명은 다음과 같습니다. | HTTP 상태 코드 | 코드 | 메시지 | 설명 | | --- | --- | --- | --- | | 200 | - | - | 각 API 문서의 응답 상태 코드를 참조 | | 201 | - | - | 각 API 문서의 응답 상태 코드를 참조 | | 204 | - | - | 각 API 문서의 응답 상태 코드를 참조 | | 400 | BadRequest | The request is malformed or contains an error such as an invalid parameter value or a missing required parameter. | 각 API 문서의 응답 상태 코드를 참조 | | 400 | LimitExceeded | The request exceeds the resource limit. | 각 API 문서의 응답 상태 코드를 참조 | | 401 | Unauthorized | Invalid authentication credentials. | 유효하지 않은 인증 정보 | | 403 | Forbidden | You do not have sufficient permissions to perform this action. | 각 API 문서의 응답 상태 코드를 참조 | | 403 | AccessDenied | The request was denied by an access policy. | 각 API 문서의 응답 상태 코드를 참조 | | 404 | NotFound | One or more of the resources in the request does not exist in the system. | 각 API 문서의 응답 상태 코드를 참조 | | 404 | RoleNotFound | The specified role could not be found. | 각 API 문서의 응답 상태 코드를 참조 | | 404 | SubAccountNotFound | The specified sub account could not be found. | 각 API 문서의 응답 상태 코드를 참조 | | 404 | AccessKeyNotFound | The specified access key could not be found. | 각 API 문서의 응답 상태 코드를 참조 | | 404 | GroupNotFound | The specified group could not be found. | 각 API 문서의 응답 상태 코드를 참조 | | 409 | AlreadyExists | A resource with the requested identifier already exists. | 각 API 문서의 응답 상태 코드를 참조 | | 409 | ResourceInUse | The specified resource is in use. | 각 API 문서의 응답 상태 코드를 참조 | | 409 | Conflict | The request could not be processed because of a conflict in the current status of the resource. | 각 API 문서의 응답 상태 코드를 참조 | | 500 | InternalServerError | The request processing has failed because of an unknown error, exception, or failure. | 서버 내부 오류 발생 | 참고 네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/api-call-std-errorhandling)를 참조해 주십시오. ## Sub Account API Sub Account 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다. ### Sub Account Sub Account 관련 API에 대한 설명은 다음과 같습니다. | API | 설명 | | --- | --- | | [createAccessKey](/docs/gov-iam-v2-sub-account-createaccesskey) | 액세스 키 생성 | | [createSubAccount](/docs/gov-iam-v2-sub-account-createsubaccount) | 서브 계정 생성 | | [getApiAccessRule](/docs/gov-iam-v2-sub-account-getapiaccessrule) | API 접근 규칙 조회 | | [getConsoleAccessRule](/docs/gov-iam-v2-sub-account-getconsoleaccessrule) | 콘솔 접근 규칙 조회 | | [getIdleDisableSetting](/docs/gov-iam-v2-sub-account-getidledisablesetting) | 장기 미사용 비활성화 설정 조회 | | [getLastAccessSummary](/docs/gov-iam-v2-sub-account-getlastaccesssummary) | 서브 계정 최근 접근 요약 조회 | | [getLoginAlias](/docs/gov-iam-v2-sub-account-getloginalias) | 로그인 별칭 조회 | | [getSubAccount](/docs/gov-iam-v2-sub-account-getsubaccount) | 서브 계정 상세 조회 | | [getSubAccountMfa](/docs/gov-iam-v2-sub-account-getsubaccountmfa) | 서브 계정 MFA 정보 조회 | | [getSubAccountPasswordPolicy](/docs/gov-iam-v2-sub-account-getsubaccountpasswordpolicy) | 서브 계정 비밀번호 정책 조회 | | [getSubAccountSessionPolicy](/docs/gov-iam-v2-sub-account-getsubaccountsessionpolicy) | 서브 계정 세션 정책 조회 | | [getUser](/docs/gov-iam-v2-sub-account-getuser) | 서브 계정 사용자 정보 조회 | | [listAccessKeys](/docs/gov-iam-v2-sub-account-listaccesskeys) | 액세스 키 목록 조회 | | [listSubAccountTags](/docs/gov-iam-v2-sub-account-listsubaccounttags) | 서브 계정 태그 목록 조회 | | [listSubAccounts](/docs/gov-iam-v2-sub-account-listsubaccounts) | 서브 계정 목록 조회 | | [updateApiAccessRule](/docs/gov-iam-v2-sub-account-updateapiaccessrule) | API 접근 규칙 수정 | | [updateConsoleAccessRule](/docs/gov-iam-v2-sub-account-updateconsoleaccessrule) | 콘솔 접근 규칙 수정 | | [updateIdleDisableSetting](/docs/gov-iam-v2-sub-account-updateidledisablesetting) | 장기 미사용 비활성화 설정 수정 | | [updateSubAccountPasswordPolicy](/docs/gov-iam-v2-sub-account-updatesubaccountpasswordpolicy) | 서브 계정 비밀번호 정책 수정 | | [updateSubAccountSessionPolicy](/docs/gov-iam-v2-sub-account-updatesubaccountsessionpolicy) | 서브 계정 세션 정책 수정 | | [updateLoginAlias](/docs/gov-iam-v2-sub-account-updateloginalias) | 로그인 별칭 수정 | | [updateSubAccount](/docs/gov-iam-v2-sub-account-updatesubaccount) | 서브 계정 수정 | | [deleteAccessKey](/docs/gov-iam-v2-sub-account-deleteaccesskey) | 액세스 키 삭제 | | [deleteSubAccount](/docs/gov-iam-v2-sub-account-deletesubaccount) | 서브 계정 삭제 | | [addSubAccountTag](/docs/gov-iam-v2-sub-account-addsubaccounttag) | 서브 계정 태그 추가 | | [attachSubAccountGroups](/docs/gov-iam-v2-sub-account-attachsubaccountgroups) | 서브 계정에 그룹 연결 | | [attachSubAccountPolicies](/docs/gov-iam-v2-sub-account-attachsubaccountpolicies) | 서브 계정에 정책 연결 | | [changeAccessKeyStatus](/docs/gov-iam-v2-sub-account-changeaccesskeystatus) | 액세스 키 상태 변경 | | [checkLoginId](/docs/gov-iam-v2-sub-account-checkloginid) | 로그인 아이디 사용 가능 여부 확인 | | [checkPassword](/docs/gov-iam-v2-sub-account-checkpassword) | 비밀번호 사용 가능 여부 확인 | | [detachSubAccountGroups](/docs/gov-iam-v2-sub-account-detachsubaccountgroups) | 서브 계정에서 그룹 연결 해제 | | [detachSubAccountPolicies](/docs/gov-iam-v2-sub-account-detachsubaccountpolicies) | 서브 계정에서 정책 연결 해제 | | [removeSubAccountTag](/docs/gov-iam-v2-sub-account-removesubaccounttag) | 서브 계정 태그 삭제 | | [resetPassword](/docs/gov-iam-v2-sub-account-resetpassword) | 서브 계정 비밀번호 재설정 | | [resolveSubAccountNos](/docs/gov-iam-v2-sub-account-resolvesubaccountnos) | 서브 계정 번호를 식별자로 변환 | ### Group Group 관련 API에 대한 설명은 다음과 같습니다. | API | 설명 | | --- | --- | | [createGroup](/docs/gov-iam-v2-group-creategroup) | 그룹 생성 | | [getGroup](/docs/gov-iam-v2-group-getgroup) | 그룹 상세 조회 | | [listGroupTags](/docs/gov-iam-v2-group-listgrouptags) | 그룹 태그 목록 조회 | | [listGroups](/docs/gov-iam-v2-group-listgroups) | 그룹 목록 조회 | | [updateGroup](/docs/gov-iam-v2-group-updategroup) | 그룹 수정 | | [deleteGroup](/docs/gov-iam-v2-group-deletegroup) | 그룹 삭제 | | [addGroupTag](/docs/gov-iam-v2-group-addgrouptag) | 그룹 태그 추가 | | [attachGroupPolicies](/docs/gov-iam-v2-group-attachgrouppolicies) | 그룹에 정책 연결 | | [attachGroupSubAccounts](/docs/gov-iam-v2-group-attachgroupsubaccounts) | 그룹에 서브 계정 연결 | | [detachGroupPolicies](/docs/gov-iam-v2-group-detachgrouppolicies) | 그룹에서 정책 연결 해제 | | [detachGroupSubAccounts](/docs/gov-iam-v2-group-detachgroupsubaccounts) | 그룹에서 서브 계정 연결 해제 | | [removeGroupTag](/docs/gov-iam-v2-group-removegrouptag) | 그룹 태그 삭제 | ### Policy Policy 관련 API에 대한 설명은 다음과 같습니다. | API | 설명 | | --- | --- | | [createPolicy](/docs/gov-iam-v2-policy-createpolicy) | 정책 생성 | | [getPolicy](/docs/gov-iam-v2-policy-getpolicy) | 정책 상세 조회 | | [listPolicies](/docs/gov-iam-v2-policy-listpolicies) | 정책 목록 조회 | | [listPolicyResources](/docs/gov-iam-v2-policy-listpolicyresources) | 정책 리소스 목록 조회 | | [listPolicyTags](/docs/gov-iam-v2-policy-listpolicytags) | 정책 태그 목록 조회 | | [updatePolicy](/docs/gov-iam-v2-policy-updatepolicy) | 정책 수정 | | [deletePolicy](/docs/gov-iam-v2-policy-deletepolicy) | 정책 삭제 | | [addPolicyTag](/docs/gov-iam-v2-policy-addpolicytag) | 정책 태그 추가 | | [deletePolicies](/docs/gov-iam-v2-policy-deletepolicies) | 여러 정책 일괄 삭제 | | [removePolicyTag](/docs/gov-iam-v2-policy-removepolicytag) | 정책 태그 삭제 | | [validatePolicy](/docs/gov-iam-v2-policy-validatepolicy) | 정책 검증 | ### Role Role 관련 API에 대한 설명은 다음과 같습니다. | API | 설명 | | --- | --- | | [createRole](/docs/gov-iam-v2-role-createrole) | 역할 생성 | | [createSwitchableRole](/docs/gov-iam-v2-role-createswitchablerole) | 전환 가능 역할 추가 | | [getRole](/docs/gov-iam-v2-role-getrole) | 역할 상세 조회 | | [getRoleAccount](/docs/gov-iam-v2-role-getroleaccount) | 역할의 대상 계정 조회 | | [getSwitchableRole](/docs/gov-iam-v2-role-getswitchablerole) | 전환 가능 역할 단건 조회 | | [listRoleTags](/docs/gov-iam-v2-role-listroletags) | 역할 태그 목록 조회 | | [listRoles](/docs/gov-iam-v2-role-listroles) | 역할 목록 조회 | | [listSwitchableRoles](/docs/gov-iam-v2-role-listswitchableroles) | 전환 가능 역할 목록 조회 | | [updateSwitchableRole](/docs/gov-iam-v2-role-updateswitchablerole) | 전환 가능 역할 수정 | | [updateRole](/docs/gov-iam-v2-role-updaterole) | 역할 수정 | | [deleteRole](/docs/gov-iam-v2-role-deleterole) | 역할 삭제 | | [deleteSwitchableRole](/docs/gov-iam-v2-role-deleteswitchablerole) | 전환 가능 역할 삭제 | | [addRoleTag](/docs/gov-iam-v2-role-addroletag) | 역할 태그 추가 | | [attachRoleAccount](/docs/gov-iam-v2-role-attachroleaccount) | 역할에 대상 계정 연결 | | [attachRoleEntities](/docs/gov-iam-v2-role-attachroleentities) | 역할에 엔티티 연결 | | [attachRolePolicies](/docs/gov-iam-v2-role-attachrolepolicies) | 역할에 정책 연결 | | [changeRoleStatus](/docs/gov-iam-v2-role-changerolestatus) | 역할 상태 변경 | | [changeRolesStatus](/docs/gov-iam-v2-role-changerolesstatus) | 여러 역할의 상태 변경 | | [deleteSwitchableRoles](/docs/gov-iam-v2-role-deleteswitchableroles) | 전환 가능 역할 일괄 삭제 | | [detachRoleAccount](/docs/gov-iam-v2-role-detachroleaccount) | 역할에서 대상 계정 연결 해제 | | [detachRoleEntities](/docs/gov-iam-v2-role-detachroleentities) | 역할에서 엔티티 연결 해제 | | [detachRolePolicies](/docs/gov-iam-v2-role-detachrolepolicies) | 역할에서 정책 연결 해제 | | [removeRoleTag](/docs/gov-iam-v2-role-removeroletag) | 역할 태그 삭제 | ## Sub Account 연관 콘텐츠 Sub Account API에 대한 사용자의 이해를 돕기 위해 다양한 연관 콘텐츠를 제공하고 있습니다. - Sub Account API 사용 방법 - [API 개요](/docs/api-overview): 네이버 클라우드 플랫폼에서 발급받은 Access Key, Secret Key 발급 및 확인, 요청 헤더에 필요한 서명 생성 방법 - [Sub Account 사용 가이드](https://guide-gov.ncloud-docs.com/docs/subaccount-overview): 서브 계정의 Access Key 발급 및 확인 방법 - [API Gateway 사용 가이드](https://guide-gov.ncloud-docs.com/docs/api-gateway-overview): 요청 헤더에 필요한 API Key 확인 방법 - Sub Account 서비스 사용 방법 - [Sub Account 사용 가이드](https://guide-gov.ncloud-docs.com/docs/subaccount-overview): 네이버 클라우드 플랫폼 콘솔에서 Sub Account 사용하는 방법 - [Ncloud 사용 환경 가이드](https://guide-gov.ncloud-docs.com/docs/environment-environment-1-1): VPC, Classic 환경 및 지원 여부에 대한 가이드 - [요금 소개, 특징, 상세 기능](https://www.gov-ncloud.com/product/management/subAccount): Sub Account의 요금 체계, 특징, 상세 기능 요약 - [서비스 최신 소식](https://www.gov-ncloud.com/intro/news): Sub Account 관련 최신 소식 - [자주 하는 질문](https://www.gov-ncloud.com/support/faq/prod?categoryCode2=MGMT&categoryCode3=SV_0078&page=1): Sub Account 사용자들이 자주 하는 질문 - [문의하기](https://www.gov-ncloud.com/v2/support/question/service): 사용 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의