Role Definitions - Create Or Update

Service:: Key Vault

API Version:: 2025-07-01

Creates or updates a custom role definition.

PUT {vaultBaseUrl}/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionName}?api-version=2025-07-01

URI Parameters

Name	In	Required	Type	Description
roleDefinitionName	path	True	string	The name of the role definition to create or update. It can be any valid GUID.
scope	path	True	string	The scope of the role definition to create or update. Managed HSM only supports '/'.
vaultBaseUrl	path	True	string (uri)
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
properties	True	RoleDefinitionProperties	Role definition properties.

Responses

Name	Type	Description
201 Created	RoleDefinition	The request has succeeded and a new resource has been created as a result.
Other Status Codes	KeyVaultError	An unexpected error response.

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://vault.azure.net/.default

Examples

Create or update a custom role definition

Sample request

HTTP

PUT https://myvault.vault.azure.net//keys/providers/Microsoft.Authorization/roleDefinitions/00000000-0000-0000-0000-000000000000?api-version=2025-07-01

{
  "properties": {
    "roleName": "My custom role",
    "type": "CustomRole",
    "description": "Role description",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.KeyVault/managedHsm/keys/sign/action"
        ]
      }
    ]
  }
}

Sample response

Status code:: 201

{
  "properties": {
    "roleName": "My custom role",
    "type": "CustomRole",
    "description": "Role description",
    "assignableScopes": [
      "/"
    ],
    "permissions": [
      {
        "dataActions": [
          "Microsoft.KeyVault/managedHsm/keys/sign/action"
        ]
      }
    ]
  },
  "id": "Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/00000000-0000-0000-0000-000000000000",
  "type": "Microsoft.Authorization/roleDefinitions",
  "name": "00000000-0000-0000-0000-000000000000"
}

Definitions

Name	Description
DataAction	Supported permissions for data actions.
Error
KeyVaultError	The key vault error exception.
Permission	Role definition permissions.
RoleDefinition	Role definition.
RoleDefinitionCreateParameters	Role definition create parameters.
RoleDefinitionProperties	Role definition properties.
RoleDefinitionType	The role definition type.
RoleScope	The role scope.
RoleType	The role type.

DataAction

Enumeration

Supported permissions for data actions.

Value	Description
Microsoft.KeyVault/managedHsm/keys/read/action	Read HSM key metadata.
Microsoft.KeyVault/managedHsm/keys/write/action	Update an HSM key.
Microsoft.KeyVault/managedHsm/keys/deletedKeys/read/action	Read deleted HSM key.
Microsoft.KeyVault/managedHsm/keys/deletedKeys/recover/action	Recover deleted HSM key.
Microsoft.KeyVault/managedHsm/keys/backup/action	Backup HSM keys.
Microsoft.KeyVault/managedHsm/keys/restore/action	Restore HSM keys.
Microsoft.KeyVault/managedHsm/roleAssignments/delete/action	Delete role assignment.
Microsoft.KeyVault/managedHsm/roleAssignments/read/action	Get role assignment.
Microsoft.KeyVault/managedHsm/roleAssignments/write/action	Create or update role assignment.
Microsoft.KeyVault/managedHsm/roleDefinitions/read/action	Get role definition.
Microsoft.KeyVault/managedHsm/roleDefinitions/write/action	Create or update role definition.
Microsoft.KeyVault/managedHsm/roleDefinitions/delete/action	Delete role definition.
Microsoft.KeyVault/managedHsm/keys/encrypt/action	Encrypt using an HSM key.
Microsoft.KeyVault/managedHsm/keys/decrypt/action	Decrypt using an HSM key.
Microsoft.KeyVault/managedHsm/keys/wrap/action	Wrap using an HSM key.
Microsoft.KeyVault/managedHsm/keys/unwrap/action	Unwrap using an HSM key.
Microsoft.KeyVault/managedHsm/keys/sign/action	Sign using an HSM key.
Microsoft.KeyVault/managedHsm/keys/verify/action	Verify using an HSM key.
Microsoft.KeyVault/managedHsm/keys/create	Create an HSM key.
Microsoft.KeyVault/managedHsm/keys/delete	Delete an HSM key.
Microsoft.KeyVault/managedHsm/keys/export/action	Export an HSM key.
Microsoft.KeyVault/managedHsm/keys/release/action	Release an HSM key using Secure Key Release.
Microsoft.KeyVault/managedHsm/keys/import/action	Import an HSM key.
Microsoft.KeyVault/managedHsm/keys/deletedKeys/delete	Purge a deleted HSM key.
Microsoft.KeyVault/managedHsm/securitydomain/download/action	Download an HSM security domain.
Microsoft.KeyVault/managedHsm/securitydomain/download/read	Check status of HSM security domain download.
Microsoft.KeyVault/managedHsm/securitydomain/upload/action	Upload an HSM security domain.
Microsoft.KeyVault/managedHsm/securitydomain/upload/read	Check the status of the HSM security domain exchange file.
Microsoft.KeyVault/managedHsm/securitydomain/transferkey/read	Download an HSM security domain transfer key.
Microsoft.KeyVault/managedHsm/backup/start/action	Start an HSM backup.
Microsoft.KeyVault/managedHsm/restore/start/action	Start an HSM restore.
Microsoft.KeyVault/managedHsm/backup/status/action	Read an HSM backup status.
Microsoft.KeyVault/managedHsm/restore/status/action	Read an HSM restore status.
Microsoft.KeyVault/managedHsm/rng/action	Generate random numbers.

Error

Object

Name	Type	Description
code	string	The error code.
innererror	Error	The key vault server error.
message	string	The error message.

KeyVaultError

Object

The key vault error exception.

Name	Type	Description
error	Error	The key vault server error.

Permission

Object

Role definition permissions.

Name	Type	Description
actions	string[]	Action permissions that are granted.
dataActions	DataAction[]	Data action permissions that are granted.
notActions	string[]	Action permissions that are excluded but not denied. They may be granted by other role definitions assigned to a principal.
notDataActions	DataAction[]	Data action permissions that are excluded but not denied. They may be granted by other role definitions assigned to a principal.

RoleDefinition

Object

Role definition.

Name	Type	Description
id	string	The role definition ID.
name	string	The role definition name.
properties.assignableScopes	RoleScope[]	Role definition assignable scopes.
properties.description	string	The role definition description.
properties.permissions	Permission[]	Role definition permissions.
properties.roleName	string	The role name.
properties.type	RoleType	The role type.
type	RoleDefinitionType	The role definition type.

RoleDefinitionCreateParameters

Object

Role definition create parameters.

Name	Type	Description
properties	RoleDefinitionProperties	Role definition properties.

RoleDefinitionProperties

Object

Role definition properties.

Name	Type	Description
assignableScopes	RoleScope[]	Role definition assignable scopes.
description	string	The role definition description.
permissions	Permission[]	Role definition permissions.
roleName	string	The role name.
type	RoleType	The role type.

RoleDefinitionType

Enumeration

The role definition type.

Value	Description
Microsoft.Authorization/roleDefinitions	Microsoft-defined role definitions.

RoleScope

Enumeration

The role scope.

Value	Description
/	Global scope
/keys	Keys scope

RoleType

Enumeration

The role type.

Value	Description
AKVBuiltInRole	Built in role.
CustomRole	Custom role.

Share via

Role Definitions - Create Or Update

URI Parameters

Request Body

Responses

Security

OAuth2Auth

Scopes

Examples

Create or update a custom role definition

Sample request

Sample response

Definitions

DataAction

Error

KeyVaultError

Permission

RoleDefinition

RoleDefinitionCreateParameters

RoleDefinitionProperties

RoleDefinitionType

RoleScope

RoleType