Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Create a new resourcePolicyDefinition object.
Supply a customer-authored Rego policy as JSON or plain text. For JSON requests, supply uniqueName and the JSON-escaped Rego text in rule.policy. For plain-text create requests, supply the Rego policy as the entire body; the service derives uniqueName from the package name. The service extracts the definition's unique name and semantic version from the Rego package name, and its descriptive metadata, parameter schema, and applicability information from __metadata__. Microsoft-authored built-in definitions are read-only.
Creating a definition doesn't activate it. To apply the policy, create a resourcePolicyAssignment that references a specific definition version and specifies parameter values, enabled status, and enforcement mode.
For policy structure, metadata, parameters, and examples, see Author policies with Rego.
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type | Least privileged permissions | Higher privileged permissions |
|---|---|---|
| Delegated (work or school account) | ResourcePolicyDefinition.ReadWrite.All | Not available. |
| Delegated (personal Microsoft account) | Not supported. | Not supported. |
| Application | ResourcePolicyDefinition.ReadWrite.All | Not available. |
Important
For delegated access using work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role that grants the permissions required for this operation. Resource Policy Administrator is the least privileged role supported for this operation.
HTTP request
POST /admin/resourcePolicy/definitions
Request headers
| Name | Description |
|---|---|
| Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
| Content-Type | application/json or text/plain. Required. |
Request body
For Content-Type: application/json, supply the following properties. JSON-escape the Rego policy text and supply it as a string in rule.policy.
| Property | Type | Description |
|---|---|---|
| rule | resourcePolicyRule | Required. The Rego policy in rule.policy. The service computes rule.appliesTo and the definition metadata. |
| uniqueName | String | Required. The immutable unique name, which must match the unique name in the Rego package. Must start with an ASCII letter, contain only ASCII letters, digits, or underscores, and have at most 128 characters. The prefixes microsoft and ms (including msft) and the exact names utils and input are reserved, regardless of case. Hyphens and non-ASCII characters aren't allowed. |
For Content-Type: text/plain, supply the unescaped Rego policy as the entire body. The service derives uniqueName from the Rego package name.
Both formats use the package format graph.<uniqueName>["<semantic-version>"], such as package graph.require_application_name["1.0.0"]. The version comes from the package name, and applicability comes from __metadata__.selector. For details, see resourcePolicyDefinition.
Response
If successful, this method returns 201 Created and a resourcePolicyDefinition object in the response body.
The response is JSON for either request-body format.
Examples
Example 1: Create a definition with JSON
Request
POST https://graph.microsoft.com/beta/admin/resourcePolicy/definitions
Content-Type: application/json
{
"uniqueName": "require_application_name",
"rule": {
"policy": "package graph.require_application_name[\"1.0.0\"]\n\n__metadata__ := {\n \"title\": \"Require an application name\",\n \"description\": \"Require applications to have a display name\",\n \"category\": \"identityAndTenant\",\n \"selector\": {\n \"resourceName\": \"microsoft.graph.application\",\n \"operations\": [\n \"create\",\n \"updateOrUpsert\"\n ]\n }\n}\n\ndefault deny := {\"result\": false, \"reasons\": []}\n\ndeny := {\"result\": true, \"reasons\": [\"A display name is required.\"]} if {\n object.get(input.resource, \"displayName\", \"\") == \"\"\n}\n"
}
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.resourcePolicyDefinition",
"@odata.etag": "\"972dd856-91ff-4539-be09-50ea8235b76c\"",
"uniqueName": "require_application_name",
"createdDateTime": "2026-10-22T12:00:00Z",
"lastModifiedDateTime": "2026-10-22T12:00:00Z",
"displayName": "Require an application name",
"description": "Require applications to have a display name",
"category": "identityAndTenant",
"version": "1.0.0",
"deletedDateTime": null,
"rule": {
"appliesTo": {
"operations": "create,updateOrUpsert",
"resourceName": "microsoft.graph.application",
"includeDerivedTypes": true
},
"policy": "package graph.require_application_name[\"1.0.0\"]\n\n__metadata__ := {\n \"title\": \"Require an application name\",\n \"description\": \"Require applications to have a display name\",\n \"category\": \"identityAndTenant\",\n \"selector\": {\n \"resourceName\": \"microsoft.graph.application\",\n \"operations\": [\n \"create\",\n \"updateOrUpsert\"\n ]\n }\n}\n\ndefault deny := {\"result\": false, \"reasons\": []}\n\ndeny := {\"result\": true, \"reasons\": [\"A display name is required.\"]} if {\n object.get(input.resource, \"displayName\", \"\") == \"\"\n}\n"
},
"paramsSchema": null
}
Example 2: Create a definition with a plain-text policy
The service derives require_application_name and version 1.0.0 from the package name.
Request
POST https://graph.microsoft.com/beta/admin/resourcePolicy/definitions
Content-Type: text/plain
package graph.require_application_name["1.0.0"]
__metadata__ := {
"title": "Require an application name",
"description": "Require applications to have a display name",
"category": "identityAndTenant",
"selector": {
"resourceName": "microsoft.graph.application",
"operations": ["create", "updateOrUpsert"]
}
}
default deny := {"result": false, "reasons": []}
deny := {"result": true, "reasons": ["A display name is required."]} if {
object.get(input.resource, "displayName", "") == ""
}
Response
The response is shortened for readability.
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.resourcePolicyDefinition",
"@odata.etag": "\"972dd856-91ff-4539-be09-50ea8235b76c\"",
"uniqueName": "require_application_name",
"displayName": "Require an application name",
"version": "1.0.0"
}