--- title: "createPolicy" slug: "gov-iam-v2-policy-createpolicy" updated: 2026-10-22T10:47:34Z published: 2026-10-22T10:47:34Z canonical: "api-gov.ncloud-docs.com/gov-iam-v2-policy-createpolicy" --- > ## 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. # createPolicy 이 가이드는 API 명세를 기반으로 자동 생성했습니다. Classic/VPC 환경에서 이용 가능합니다. Ncloud API 표준 규격을 적용한 API입니다. 전달된 권한 정의와 선택적 태그로 새로운 정책을 생성하고, 생성된 정책을 반환합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /policies | ### 요청 헤더 Sub Account API에서 공통으로 사용하는 헤더에 대한 정보는 [Sub Account 요청 헤더](/docs/gov-iam-v2-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `policyName` | String | Required | 생성할 정책의 이름 - 길이: 3 ~ 30 - <예시> my-policy | | `description` | String | Optional | 정책에 대한 설명 - 길이: ~ 300 - <예시> 정책 설명입니다 | | `permissions` | List<[PolicyPermissionParam](/docs/gov-iam-v2-policy-createpolicy#PolicyPermissionParam)> | Required | 정책이 부여하는 권한 목록. 각 항목은 효과(effect), 대상(상품·액션·리소스), 적용 조건으로 구성 | | `tags` | Map | Optional | 리소스에 부여할 태그의 키-값 맵 - <예시> `{"env": "dev", "team": "a"}` | | `tags.<키>` | String | - | 태그의 값 - 길이: 1 ~ 256 | #### PolicyPermissionParam 정책에 포함되는 권한(효과, 대상, 조건) | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `effect` | String | Required | 권한 효과. 값은 IAM 정책 문서 문법(Effect)의 값을 그대로 사용 - `Allow` \| `Deny` - `Allow`: targets에 지정한 대상에 대한 액션을 허용 - `Deny`: targets에 지정한 대상에 대한 액션을 거부. 같은 요청에 `Allow`와 `Deny`가 함께 적용되면 `Deny`가 우선 - <예시> Allow | | `targets` | List<[PolicyPermissionTargetParam](/docs/gov-iam-v2-policy-createpolicy#PolicyPermissionTargetParam)> | Required | 권한이 적용되는 대상(상품, 액션, 리소스) 목록 | | `condition` | Map>> | Optional | 권한 적용 조건. 조건 연산자를 키로 하고 그 아래에 조건 키와 조건 값을 두는 중첩 맵으로 지정. 연산자는 문자열 비교와 일시 비교, Null, 그리고 각 연산자에 IfExists를 붙인 변형을 지원하며, 지원하지 않는 연산자를 지정하면 400(iam.policy.invalidConditionSyntax)으로 응답. 조건 키는 요청 주체를 식별하는 ncp: 접두의 전역 속성과 태그 키를 뒤에 붙여 쓰는 형식(예: ncp:resourceTag/{tagKey})을 사용. 지원 연산자와 조건 키의 전체 목록은 정책 조건 가이드(https://guide-gov.ncloud-docs.com/docs/subaccount-condition)를 참고 - <예시> `{"StringEquals": {"ncp:resourceTag/env": "beta"}, "DateGreaterThan": {"ncp:currentTime": "2026-01-01T00:00:00Z"}}` | | `condition.<키>.<키>` | String \| List | - | 조건 값. 단일 문자열 또는 문자열 배열로 지정. 일시 비교 연산자의 값은 RFC 3339 형식의 일시 문자열이고, Null 연산자의 값은 문자열 true 또는 false | #### PolicyPermissionTargetParam 권한이 적용되는 대상(상품, 액션, 리소스) | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `product` | String | Required | 권한 대상 상품(서비스) 코드 - <예시> IAM | | `actions` | List | Required | 권한 대상 액션 목록 - <예시> `["View*", "Change*"]` | | `resourceNrns` | List | Required | 권한 대상 리소스의 NRN 목록. 리소스를 지정하지 않을 경우 `*` 입력 - <예시> `["*"]` | ### 요청 예시 요청 예시는 다음과 같습니다. ``` curl --location --request POST 'https://subaccount.apigw.gov-ntruss.com/api/v2/policies' \ --header 'x-ncp-apigw-timestamp: {Timestamp}' \ --header 'x-ncp-iam-access-key: {Access Key}' \ --header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \ --header 'Content-Type: application/json' \ --data '{ "policyName": "my-policy", "permissions": [ { "effect": "Allow", "targets": [ { "product": "IAM", "actions": [ "View*", "Change*" ], "resourceNrns": [ "*" ] } ] } ] }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `policyId` | String (uuid) | - | 정책의 식별자 - <예시> 4e066e50-9c3a-11e7-8a66-1e5021fa7c80 | | `policyName` | String | - | 정책의 이름 - <예시> my-policy | | `policyType` | String | - | 정책 유형 - `SYSTEM_MANAGED` \| `USER_CREATED` - `SYSTEM_MANAGED`: 네이버 클라우드 플랫폼이 제공하는 관리형 정책 - `USER_CREATED`: 사용자가 생성한 정책 - <예시> USER_CREATED | | `description` | String | - | 정책에 대한 설명 - <예시> 정책 설명입니다 | | `nrn` | String | - | 정책의 NRN(Ncloud Resource Name) - <예시> nrn:GOV:IAM::25000000:Policy/4e066e50-9c3a-11e7-8a66-1e5021fa7c80 | | `createdDateTime` | String (date-time) | - | 정책이 생성된 일시 - <예시> 2019-08-10T13:21:00Z | | `updatedDateTime` | String (date-time) | - | 정책이 마지막으로 수정된 일시 - <예시> 2019-08-10T13:21:00Z | | `validationResult` | Object<[PolicyValidationWarnings](/docs/gov-iam-v2-policy-createpolicy#PolicyValidationWarnings)> | - | 정책 검증에서 발견된 경고 목록. 경고가 있을 때만 포함되며, 정책은 정상 생성된 상태. 검증 실패(ERROR)는 이 필드가 아니라 400 Bad Request 표준 에러의 fieldErrors로 응답 | | `tags` | Map | - | 요청에 지정한 태그의 키-값 맵. 태그는 Resource Manager가 소유하므로 조회 응답에는 포함되지 않으며, 생성 요청에 지정한 값을 그대로 반환 - <예시> `{"env": "dev", "team": "a"}` | | `tags.<키>` | String | - | 태그의 값 - 길이: 1 ~ 256 | #### PolicyValidationWarnings 정책 생성·수정 시 검증에서 발견된 경고 목록. 경고(WARNING) 항목만 담으며, 검증 실패(ERROR)는 400 Bad Request 표준 에러의 fieldErrors로 응답하므로 포함되지 않음 | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `details` | List<[PolicyValidationResultDetail](/docs/gov-iam-v2-policy-createpolicy#PolicyValidationResultDetail)> | - | 경고 상세 항목 목록. 각 항목의 type은 WARNING | #### PolicyValidationResultDetail 정책 검증 결과 상세 항목 | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | String | - | 검증 결과 상세 항목의 심각도 유형. 정책 검증 API(POST /policies/validate) 응답에는 두 유형이 모두 나타나고, 생성·수정 응답의 validationResult에는 WARNING만 표시 - `ERROR` \| `WARNING` - `ERROR`: 정책을 생성·수정할 수 없는 오류 - `WARNING`: 정책은 생성·수정되지만 확인이 필요한 사항 - <예시> ERROR | | `code` | String | - | 검증 결과 상세 항목을 식별하는 코드. iam.error.* 또는 iam.policy.* 형식이며, 값이 추가될 수 있으므로 알 수 없는 코드는 message로 처리 필요 - <예시> iam.policy.invalidAction | | `location` | String | - | 검증 결과가 가리키는 정책 문서 내 위치 - <예시> permissions[0].targets[0] | | `message` | String | - | 검증 결과를 설명하는 메시지 - <예시> 유효하지 않은 액션입니다 | ### 응답 상태 코드 Sub Account API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Sub Account 응답 상태 코드](/docs/gov-iam-v2-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. 이 API에만 해당하는 응답 상태 코드는 다음과 같습니다. | HTTP 상태 코드 | 코드 | 메시지 | 설명 | | --- | --- | --- | --- | | 201 | - | - | 생성된 정책을 반환. 검증 경고가 있을 때만 validationResult가 포함되며, 요청에 태그를 지정한 경우 tags가 함께 반환 | | 400 | BadRequest | The request is malformed or contains an error such as an invalid parameter value or a missing required parameter. | 필수 필드 누락·형식 오류 등 입력값 검증에 실패했거나, 정책 문서 검증(존재하지 않는 상품·액션·리소스, 구문 오류, 이름 규칙 위반)에 실패. 정책 문서 검증 실패는 실패한 필드를 fieldErrors에 전량 담아 응답 | | 403 | Forbidden | You do not have sufficient permissions to perform this action. | 요청한 자원(또는 상위 자원)에 대한 접근 권한 없음. 자원의 존재 여부와 무관하게 우선 반환 | | 409 | AlreadyExists | A resource with the requested identifier already exists. | 이미 같은 이름의 정책이 존재 | ### 응답 예시 응답 예시는 다음과 같습니다. ``` { "policyId": "4e066e50-9c3a-11e7-8a66-1e5021fa7c80", "policyName": "my-policy", "policyType": "USER_CREATED", "description": "정책 설명입니다", "nrn": "nrn:GOV:IAM::25000000:Policy/4e066e50-9c3a-11e7-8a66-1e5021fa7c80", "createdDateTime": "2019-08-10T13:21:00Z", "updatedDateTime": "2019-08-10T13:21:00Z", "validationResult": { "details": [ { "type": "ERROR", "code": "iam.policy.invalidAction", "location": "permissions[0].targets[0]", "message": "유효하지 않은 액션입니다" } ] }, "tags": { "env": "dev", "team": "a" } } ```