Share via

Role Assignments - Create

Service:
Key Vault
API Version:
2025-07-01

Creates a role assignment.

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

URI Parameters

Name In Required Type Description
roleAssignmentName
 path True

string

The name of the role assignment to create. It can be any valid GUID.
scope
 path True

string

The scope of the role assignment to create.
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

RoleAssignmentProperties

Role assignment properties.

Responses

Name Type Description
201 Created

RoleAssignment

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 a role assignment

Sample request

PUT https://myvault.vault.azure.net//keys/providers/Microsoft.Authorization/roleAssignments/roleAssignmentName?api-version=2025-07-01

{
  "properties": {
    "roleDefinitionId": "/keys/providers/Microsoft.Authorization/roleDefinitions/roleDefinitionId",
    "principalId": "principalId"
  }
}

Sample response

Status code:
201 
{
  "properties": {
    "roleDefinitionId": "/keys/providers/Microsoft.Authorization/roleDefinitions/roleDefinitionId",
    "principalId": "principalId",
    "scope": "/keys"
  },
  "id": "/keys/providers/Microsoft.Authorization/roleAssignments/roleAssignmentId",
  "type": "Microsoft.Authorization/roleAssignments",
  "name": "roleAssignmentId"
}

Definitions

Name Description
Error
KeyVaultError

The key vault error exception.
RoleAssignment

Role Assignments
RoleAssignmentCreateParameters

Role assignment create parameters.
RoleAssignmentProperties

Role assignment properties.
RoleAssignmentPropertiesWithScope

Role assignment properties with scope.
RoleScope

The role scope.

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.

RoleAssignment

Object

Role Assignments

Name Type Description
id

string

The role assignment ID.
name

string

The role assignment name.
properties

RoleAssignmentPropertiesWithScope

Role assignment properties.
type

string

The role assignment type.

RoleAssignmentCreateParameters

Object

Role assignment create parameters.

Name Type Description
properties

RoleAssignmentProperties

Role assignment properties.

RoleAssignmentProperties

Object

Role assignment properties.

Name Type Description
principalId

string

The principal ID assigned to the role. This maps to the ID inside the Active Directory. It can point to a user, service principal, or security group.
roleDefinitionId

string

The role definition ID used in the role assignment.

RoleAssignmentPropertiesWithScope

Object

Role assignment properties with scope.

Name Type Description
principalId

string

The principal ID.
roleDefinitionId

string

The role definition ID.
scope

RoleScope

The role scope.

RoleScope

Enumeration

The role scope.

Value Description
/

Global scope
/keys

Keys scope