Share via

Sql Resources - Create Update Sql Role Definition

Service:
Cosmos DB Resource Provider
API Version:
2025-05-01-preview

Creates or updates an Azure Cosmos DB SQL Role Definition.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlRoleDefinitions/{roleDefinitionId}?api-version=2025-05-01-preview

URI Parameters

Name In Required Type Description
accountName
 path True

string

minLength: 3
maxLength: 50
pattern: ^[a-z0-9]+(-[a-z0-9]+)*

Cosmos DB database account name.
resourceGroupName
 path True

string

minLength: 1
maxLength: 90

The name of the resource group. The name is case insensitive.
roleDefinitionId
 path True

string

The GUID for the Role Definition.
subscriptionId
 path True

string

minLength: 1

The ID of the target subscription.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Type Description
createUpdateSqlRoleDefinitionParameters

SqlRoleDefinitionCreateUpdateParameters

The properties required to create or update a Role Definition.

Responses

Name Type Description
200 OK

SqlRoleDefinitionGetResults

The Role Definition create or update operation was completed successfully.
202 Accepted

The Role Definition create or update request was accepted and will complete asynchronously.
Other Status Codes

CloudError

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

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

Scopes

Name Description
user_impersonation Impersonate your user account

Examples

CosmosDBSqlRoleDefinitionCreateUpdate

Sample request

PUT https://management.azure.com/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/sqlRoleDefinitions/myRoleDefinitionId?api-version=2025-05-01-preview

{
  "properties": {
    "roleName": "myRoleName",
    "type": "CustomRole",
    "assignableScopes": [
      "/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/dbs/sales",
      "/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/dbs/purchases"
    ],
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/create",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read"
        ],
        "notDataActions": []
      }
    ]
  }
}

Sample response

Status code:
200 
{
  "id": "/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/sqlRoleDefinitions/myRoleDefinitionId",
  "name": "myRoleDefinitionId",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
  "properties": {
    "roleName": "myRoleName",
    "type": "CustomRole",
    "assignableScopes": [
      "/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/dbs/sales",
      "/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/myAccountName/dbs/purchases"
    ],
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/create",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read"
        ]
      }
    ]
  }
}
Status code:
202 
azure-AsyncOperation: https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/{location}/operationsStatus/{operationId}?api-version=2025-05-01-preview
location: https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/{location}/operationsStatus/{operationId}?api-version=2025-05-01-preview

Definitions

Name Description
CloudError

An error response from the service.
ErrorResponse

Error Response.
Permission

The set of operations allowed through this Role Definition.
RoleDefinitionType

Indicates whether the Role Definition was built-in or user created.
SqlRoleDefinitionCreateUpdateParameters

The properties required to create or update a Role Definition.
SqlRoleDefinitionGetResults

An Azure Cosmos DB SQL Role Definition.

CloudError

Object

An error response from the service.

Name Type Description
error

ErrorResponse

Error Response.

ErrorResponse

Object

Error Response.

Name Type Description
code

string

Error code.
message

string

Error message indicating why the operation failed.

Permission

Object

The set of operations allowed through this Role Definition.

Name Type Description
dataActions

string[]

An array of data actions that are allowed.
notDataActions

string[]

An array of data actions that are denied.

RoleDefinitionType

Enumeration

Indicates whether the Role Definition was built-in or user created.

Value Description
BuiltInRole
CustomRole

SqlRoleDefinitionCreateUpdateParameters

Object

The properties required to create or update a Role Definition.

Name Type Description
properties.assignableScopes

string[]

A set of fully qualified Scopes at or below which Role Assignments may be created using this Role Definition. This will allow application of this Role Definition on the entire database account or any underlying Database / Collection. Must have at least one element. Scopes higher than Database account are not enforceable as assignable Scopes. Note that resources referenced in assignable Scopes need not exist.
properties.permissions

Permission[]

The set of operations allowed through this Role Definition.
properties.roleName

string

A user-friendly name for the Role Definition. Must be unique for the database account.
properties.type

RoleDefinitionType

Indicates whether the Role Definition was built-in or user created.

SqlRoleDefinitionGetResults

Object

An Azure Cosmos DB SQL Role Definition.

Name Type Description
id

string

The unique resource identifier of the database account.
name

string

The name of the database account.
properties.assignableScopes

string[]

A set of fully qualified Scopes at or below which Role Assignments may be created using this Role Definition. This will allow application of this Role Definition on the entire database account or any underlying Database / Collection. Must have at least one element. Scopes higher than Database account are not enforceable as assignable Scopes. Note that resources referenced in assignable Scopes need not exist.
properties.permissions

Permission[]

The set of operations allowed through this Role Definition.
properties.roleName

string

A user-friendly name for the Role Definition. Must be unique for the database account.
properties.type

RoleDefinitionType

Indicates whether the Role Definition was built-in or user created.
type

string

The type of Azure resource.