Skip to main content

policies

Creates, updates, deletes, gets or lists a policies resource.

Overview​

Namepolicies
TypeResource
Idoci.identity.policies

Fields​

The following fields are returned by SELECT queries:

The policy was retrieved.

NameDatatypeDescription
idstringThe OCID of the policy.
namestringThe name you assign to the policy during creation. The name must be unique across all policies in the tenancy and cannot be changed.
compartmentIdstringThe OCID of the compartment containing the policy (either the tenancy or another compartment).
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
descriptionstringThe description you assign to the policy. Does not have to be unique, and it's changeable.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
inactiveStatusinteger (int64)The detailed status of INACTIVE lifecycleState.
lifecycleStatestringThe policy's current state. After creating a policy, make sure its lifecycleState changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
locksarrayLocks associated with this resource.
statementsarrayAn array of one or more policy statements written in the policy language.
timeCreatedstring (date-time)Date and time the policy was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z
versionDatestring (date-time)The version of the policy. If null or set to an empty string, when a request comes in for authorization, the policy will be evaluated according to the current behavior of the services at that moment. If set to a particular date (YYYY-MM-DD), the policy will be evaluated according to the behavior of the services on that date.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectpolicyId, regionGets the specified policy's information.
listselectcompartmentId, regionpage, limit, name, sortBy, sortOrder, lifecycleStateLists the policies in the specified compartment (either the tenancy or another of your compartments).<br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br /><br />To determine which policies apply to a particular group or compartment, you must view the individual<br />statements inside all your policies. There isn't a way to automatically obtain that information via the API.<br />
createinsertregion, name, compartmentId, statements, descriptionopc-retry-tokenCreates a new policy in the specified compartment (either the tenancy or another of your compartments).<br />If you're new to policies, see [Get Started with Policies](/Content/Identity/policiesgs/get-started-with-policies.htm).<br /><br />You must specify a name for the policy, which must be unique across all policies in your tenancy<br />and cannot be changed.<br /><br />You must also specify a description for the policy (although it can be an empty string). It does not<br />have to be unique, and you can change it anytime with [UpdatePolicy](#/en/identity/20160918/Policy/UpdatePolicy).<br /><br />You must specify one or more policy statements in the statements array. For information about writing<br />policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm) and<br />[Common Policies](/Content/Identity/policiescommon/commonpolicies.htm).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />New policies take effect typically within 10 seconds.<br />
updateupdatepolicyId, regionif-match, isLockOverrideUpdates the specified policy. You can update the description or the policy statements themselves.<br /><br />Policy changes take effect typically within 10 seconds.<br />
deletedeletepolicyId, regionif-match, isLockOverrideDeletes the specified policy. The deletion takes effect typically within 10 seconds.
add_policy_lockexecpolicyId, region, typeif-match, opc-request-id, opc-retry-tokenAdd a resource lock to a tag namespace.<br />
remove_policy_lockexecpolicyId, region, typeif-match, opc-request-id, opc-retry-tokenRemove a resource lock to a policy<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment (remember that the tenancy is simply the root compartment).
policyIdstringThe OCID of the policy.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
isLockOverridebooleanWhether to override locks (if any exist).
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return in a paginated "List" call.
namestringA filter to only return resources that match the given name exactly.
opc-request-idstringUnique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for NAME is ascending. The NAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by Availability Domain if the scope of the resource type is within a single Availability Domain. If you call one of these "List" operations without specifying an Availability Domain, the resources are grouped by Availability Domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The NAME sort order is case sensitive.

SELECT examples​

Gets the specified policy's information.

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
locks,
statements,
timeCreated,
versionDate
FROM oci.identity.policies
WHERE policyId = '{{ policyId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new policy in the specified compartment (either the tenancy or another of your compartments).<br />If you're new to policies, see [Get Started with Policies](/Content/Identity/policiesgs/get-started-with-policies.htm).<br /><br />You must specify a name for the policy, which must be unique across all policies in your tenancy<br />and cannot be changed.<br /><br />You must also specify a description for the policy (although it can be an empty string). It does not<br />have to be unique, and you can change it anytime with [UpdatePolicy](#/en/identity/20160918/Policy/UpdatePolicy).<br /><br />You must specify one or more policy statements in the statements array. For information about writing<br />policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm) and<br />[Common Policies](/Content/Identity/policiescommon/commonpolicies.htm).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />New policies take effect typically within 10 seconds.<br />

INSERT INTO oci.identity.policies (
compartmentId,
definedTags,
description,
freeformTags,
locks,
name,
statements,
versionDate,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ freeformTags }}',
'{{ locks }}',
'{{ name }}' /* required */,
'{{ statements }}' /* required */,
'{{ versionDate }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
locks,
statements,
timeCreated,
versionDate
;

UPDATE examples​

Updates the specified policy. You can update the description or the policy statements themselves.<br /><br />Policy changes take effect typically within 10 seconds.<br />

UPDATE oci.identity.policies
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}',
statements = '{{ statements }}',
versionDate = '{{ versionDate }}'
WHERE 
policyId = '{{ policyId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND isLockOverride = {{ isLockOverride}}
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
locks,
statements,
timeCreated,
versionDate;

DELETE examples​

Deletes the specified policy. The deletion takes effect typically within 10 seconds.

DELETE FROM oci.identity.policies
WHERE policyId = '{{ policyId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND isLockOverride = '{{ isLockOverride }}'
;

Lifecycle Methods​

Add a resource lock to a tag namespace.<br />

EXEC oci.identity.policies.add_policy_lock 
@policyId='{{ policyId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"message": "{{ message }}", 
"relatedResourceId": "{{ relatedResourceId }}", 
"type": "{{ type }}"
}'
;