Role Definitions - Create Or Update

Creates or updates a custom role definition.

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

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

The vault name, for example https://myvault.vault.azure.net.

api-version
query True

string

Client API version.

Request Body

Name Required Type Description
properties True

RoleDefinitionProperties

Role definition properties.

Responses

Name Type Description
201 Created

RoleDefinition

Created - Returns information about the role definition.

Other Status Codes

KeyVaultError

Key Vault error response describing why the operation failed.

Examples

PutRoleDefinition

Sample request

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

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

Sample response

{
  "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

The key vault server 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

Supported permissions for data actions.

Name Type Description
Microsoft.KeyVault/managedHsm/backup/start/action

string

Start an HSM backup.

Microsoft.KeyVault/managedHsm/backup/status/action

string

Read an HSM backup status.

Microsoft.KeyVault/managedHsm/keys/backup/action

string

Backup HSM keys.

Microsoft.KeyVault/managedHsm/keys/create

string

Create an HSM key.

Microsoft.KeyVault/managedHsm/keys/decrypt/action

string

Decrypt using an HSM key.

Microsoft.KeyVault/managedHsm/keys/delete

string

Delete an HSM key.

Microsoft.KeyVault/managedHsm/keys/deletedKeys/delete

string

Purge a deleted HSM key.

Microsoft.KeyVault/managedHsm/keys/deletedKeys/read/action

string

Read deleted HSM key.

Microsoft.KeyVault/managedHsm/keys/deletedKeys/recover/action

string

Recover deleted HSM key.

Microsoft.KeyVault/managedHsm/keys/encrypt/action

string

Encrypt using an HSM key.

Microsoft.KeyVault/managedHsm/keys/export/action

string

Export an HSM key.

Microsoft.KeyVault/managedHsm/keys/import/action

string

Import an HSM key.

Microsoft.KeyVault/managedHsm/keys/read/action

string

Read HSM key metadata.

Microsoft.KeyVault/managedHsm/keys/release/action

string

Release an HSM key using Secure Key Release.

Microsoft.KeyVault/managedHsm/keys/restore/action

string

Restore HSM keys.

Microsoft.KeyVault/managedHsm/keys/sign/action

string

Sign using an HSM key.

Microsoft.KeyVault/managedHsm/keys/unwrap/action

string

Unwrap using an HSM key.

Microsoft.KeyVault/managedHsm/keys/verify/action

string

Verify using an HSM key.

Microsoft.KeyVault/managedHsm/keys/wrap/action

string

Wrap using an HSM key.

Microsoft.KeyVault/managedHsm/keys/write/action

string

Update an HSM key.

Microsoft.KeyVault/managedHsm/restore/start/action

string

Start an HSM restore.

Microsoft.KeyVault/managedHsm/restore/status/action

string

Read an HSM restore status.

Microsoft.KeyVault/managedHsm/rng/action

string

Generate random numbers.

Microsoft.KeyVault/managedHsm/roleAssignments/delete/action

string

Delete role assignment.

Microsoft.KeyVault/managedHsm/roleAssignments/read/action

string

Get role assignment.

Microsoft.KeyVault/managedHsm/roleAssignments/write/action

string

Create or update role assignment.

Microsoft.KeyVault/managedHsm/roleDefinitions/delete/action

string

Delete role definition.

Microsoft.KeyVault/managedHsm/roleDefinitions/read/action

string

Get role definition.

Microsoft.KeyVault/managedHsm/roleDefinitions/write/action

string

Create or update role definition.

Microsoft.KeyVault/managedHsm/securitydomain/download/action

string

Download an HSM security domain.

Microsoft.KeyVault/managedHsm/securitydomain/download/read

string

Check status of HSM security domain download.

Microsoft.KeyVault/managedHsm/securitydomain/transferkey/read

string

Download an HSM security domain transfer key.

Microsoft.KeyVault/managedHsm/securitydomain/upload/action

string

Upload an HSM security domain.

Microsoft.KeyVault/managedHsm/securitydomain/upload/read

string

Check the status of the HSM security domain exchange file.

Error

The key vault server error.

Name Type Description
code

string

The error code.

innererror

Error

The key vault server error.

message

string

The error message.

KeyVaultError

The key vault error exception.

Name Type Description
error

Error

The key vault server error.

Permission

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

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

Role definition create parameters.

Name Type Description
properties

RoleDefinitionProperties

Role definition properties.

RoleDefinitionProperties

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

The role definition type.

Name Type Description
Microsoft.Authorization/roleDefinitions

string

RoleScope

The role scope.

Name Type Description
/

string

Global scope

/keys

string

Keys scope

RoleType

The role type.

Name Type Description
AKVBuiltInRole

string

Built in role.

CustomRole

string

Custom role.