{ "swagger": "2.0", "info": { "title": "Cosmos DB", "description": "Azure Cosmos DB Role Based Access Control Resource Provider REST API", "version": "2025-10-15" }, "host": "management.azure.com", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "security": [ { "azure_auth": [ "user_impersonation" ] } ], "securityDefinitions": { "azure_auth": { "type": "oauth2", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "flow": "implicit", "description": "Azure Active Directory OAuth2 Flow", "scopes": { "user_impersonation": "Impersonate your user account" } } }, "paths": { "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlRoleDefinitions/{roleDefinitionId}": { "get": { "operationId": "SqlResources_GetSqlRoleDefinition", "x-ms-examples": { "CosmosDBSqlRoleDefinitionGet": { "$ref": "./examples/CosmosDBSqlRoleDefinitionGet.json" } }, "description": "Retrieves the properties of an existing Azure Cosmos DB SQL Role Definition with the given Id.", "parameters": [ { "$ref": "#/parameters/roleDefinitionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The Role Definition was successfully retrieved.", "schema": { "$ref": "#/definitions/SqlRoleDefinitionGetResults" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } }, "put": { "operationId": "SqlResources_CreateUpdateSqlRoleDefinition", "x-ms-examples": { "CosmosDBSqlRoleDefinitionCreateUpdate": { "$ref": "./examples/CosmosDBSqlRoleDefinitionCreateUpdate.json" } }, "x-ms-long-running-operation": true, "description": "Creates or updates an Azure Cosmos DB SQL Role Definition.", "parameters": [ { "$ref": "#/parameters/roleDefinitionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "name": "createUpdateSqlRoleDefinitionParameters", "in": "body", "required": true, "description": "The properties required to create or update a Role Definition.", "schema": { "$ref": "#/definitions/SqlRoleDefinitionCreateUpdateParameters" } } ], "responses": { "200": { "description": "The Role Definition create or update operation was completed successfully.", "schema": { "$ref": "#/definitions/SqlRoleDefinitionGetResults" } }, "202": { "description": "The Role Definition create or update request was accepted and will complete asynchronously." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } }, "delete": { "operationId": "SqlResources_DeleteSqlRoleDefinition", "x-ms-examples": { "CosmosDBSqlRoleDefinitionDelete": { "$ref": "./examples/CosmosDBSqlRoleDefinitionDelete.json" } }, "x-ms-long-running-operation": true, "description": "Deletes an existing Azure Cosmos DB SQL Role Definition.", "parameters": [ { "$ref": "#/parameters/roleDefinitionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The Role Definition delete operation was completed successfully." }, "202": { "description": "The Role Definition delete request was accepted and will complete asynchronously." }, "204": { "description": "The requested Role Definition does not exist." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlRoleDefinitions": { "get": { "operationId": "SqlResources_ListSqlRoleDefinitions", "x-ms-examples": { "CosmosDBSqlRoleDefinitionList": { "$ref": "./examples/CosmosDBSqlRoleDefinitionList.json" } }, "x-ms-pageable": { "nextLinkName": null }, "description": "Retrieves the list of all Azure Cosmos DB SQL Role Definitions.", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The list operation completed successfully.", "schema": { "$ref": "#/definitions/SqlRoleDefinitionListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlRoleAssignments/{roleAssignmentId}": { "get": { "operationId": "SqlResources_GetSqlRoleAssignment", "x-ms-examples": { "CosmosDBSqlRoleAssignmentGet": { "$ref": "./examples/CosmosDBSqlRoleAssignmentGet.json" } }, "description": "Retrieves the properties of an existing Azure Cosmos DB SQL Role Assignment with the given Id.", "parameters": [ { "$ref": "#/parameters/roleAssignmentIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The Role Assignment was successfully retrieved.", "schema": { "$ref": "#/definitions/SqlRoleAssignmentGetResults" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } }, "put": { "operationId": "SqlResources_CreateUpdateSqlRoleAssignment", "x-ms-examples": { "CosmosDBSqlRoleAssignmentCreateUpdate": { "$ref": "./examples/CosmosDBSqlRoleAssignmentCreateUpdate.json" } }, "x-ms-long-running-operation": true, "description": "Creates or updates an Azure Cosmos DB SQL Role Assignment.", "parameters": [ { "$ref": "#/parameters/roleAssignmentIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "name": "createUpdateSqlRoleAssignmentParameters", "in": "body", "required": true, "description": "The properties required to create or update a Role Assignment.", "schema": { "$ref": "#/definitions/SqlRoleAssignmentCreateUpdateParameters" } } ], "responses": { "200": { "description": "The Role Assignment create or update operation was completed successfully.", "schema": { "$ref": "#/definitions/SqlRoleAssignmentGetResults" } }, "202": { "description": "The Role Assignment create or update request was accepted and will complete asynchronously." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } }, "delete": { "operationId": "SqlResources_DeleteSqlRoleAssignment", "x-ms-examples": { "CosmosDBSqlRoleAssignmentDelete": { "$ref": "./examples/CosmosDBSqlRoleAssignmentDelete.json" } }, "x-ms-long-running-operation": true, "description": "Deletes an existing Azure Cosmos DB SQL Role Assignment.", "parameters": [ { "$ref": "#/parameters/roleAssignmentIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The Role Assignment delete operation was completed successfully." }, "202": { "description": "The Role Assignment delete request was accepted and will complete asynchronously." }, "204": { "description": "The requested Role Assignment does not exist." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlRoleAssignments": { "get": { "operationId": "SqlResources_ListSqlRoleAssignments", "x-ms-examples": { "CosmosDBSqlRoleAssignmentList": { "$ref": "./examples/CosmosDBSqlRoleAssignmentList.json" } }, "x-ms-pageable": { "nextLinkName": null }, "description": "Retrieves the list of all Azure Cosmos DB SQL Role Assignments.", "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "cosmos-db.json#/parameters/accountNameParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The list operation completed successfully.", "schema": { "$ref": "#/definitions/SqlRoleAssignmentListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "cosmos-db.json#/definitions/CloudError" } } } } } }, "definitions": { "SqlRoleDefinitionResource": { "properties": { "roleName": { "type": "string", "description": "A user-friendly name for the Role Definition. Must be unique for the database account." }, "type": { "type": "string", "enum": [ "BuiltInRole", "CustomRole" ], "description": "Indicates whether the Role Definition was built-in or user created.", "x-ms-enum": { "name": "RoleDefinitionType", "modelAsString": false } }, "assignableScopes": { "type": "array", "items": { "type": "string" }, "description": "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." }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/Permission" }, "description": "The set of operations allowed through this Role Definition." } }, "description": "Azure Cosmos DB SQL Role Definition resource object." }, "SqlRoleDefinitionCreateUpdateParameters": { "description": "Parameters to create and update an Azure Cosmos DB SQL Role Definition.", "type": "object", "properties": { "properties": { "x-ms-client-flatten": true, "description": "Properties to create and update an Azure Cosmos DB SQL Role Definition.", "$ref": "#/definitions/SqlRoleDefinitionResource" } } }, "SqlRoleDefinitionGetResults": { "type": "object", "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/SqlRoleDefinitionResource", "description": "Properties related to the Role Definition." } }, "allOf": [ { "$ref": "cosmos-db.json#/definitions/ARMProxyResource" } ], "description": "An Azure Cosmos DB SQL Role Definition." }, "Permission": { "type": "object", "properties": { "dataActions": { "type": "array", "items": { "type": "string" }, "description": "An array of data actions that are allowed." }, "notDataActions": { "type": "array", "items": { "type": "string" }, "description": "An array of data actions that are denied." } }, "description": "The set of data plane operations permitted through this Role Definition." }, "SqlRoleDefinitionListResult": { "properties": { "value": { "type": "array", "readOnly": true, "items": { "$ref": "#/definitions/SqlRoleDefinitionGetResults" }, "description": "List of Role Definitions and their properties." } }, "description": "The relevant Role Definitions." }, "SqlRoleAssignmentResource": { "type": "object", "properties": { "roleDefinitionId": { "type": "string", "description": "The unique identifier for the associated Role Definition." }, "scope": { "type": "string", "description": "The data plane resource path for which access is being granted through this Role Assignment." }, "principalId": { "type": "string", "description": "The unique identifier for the associated AAD principal in the AAD graph to which access is being granted through this Role Assignment. Tenant ID for the principal is inferred using the tenant associated with the subscription." } }, "description": "Azure Cosmos DB SQL Role Assignment resource object." }, "SqlRoleAssignmentCreateUpdateParameters": { "description": "Parameters to create and update an Azure Cosmos DB SQL Role Assignment.", "type": "object", "properties": { "properties": { "x-ms-client-flatten": true, "description": "Properties to create and update an Azure Cosmos DB SQL Role Assignment.", "$ref": "#/definitions/SqlRoleAssignmentResource" } } }, "SqlRoleAssignmentGetResults": { "type": "object", "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/SqlRoleAssignmentResource", "description": "Properties related to the Role Assignment." } }, "allOf": [ { "$ref": "cosmos-db.json#/definitions/ARMProxyResource" } ], "description": "An Azure Cosmos DB Role Assignment" }, "SqlRoleAssignmentListResult": { "properties": { "value": { "type": "array", "readOnly": true, "items": { "$ref": "#/definitions/SqlRoleAssignmentGetResults" }, "description": "List of Role Assignments and their properties" } }, "description": "The relevant Role Assignments." } }, "parameters": { "roleDefinitionIdParameter": { "name": "roleDefinitionId", "in": "path", "required": true, "type": "string", "x-ms-parameter-location": "method", "description": "The GUID for the Role Definition." }, "roleAssignmentIdParameter": { "name": "roleAssignmentId", "in": "path", "required": true, "type": "string", "x-ms-parameter-location": "method", "description": "The GUID for the Role Assignment." } } }