> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # Create document permission > Creates a new permission assignment for a user or group within the document, granting them specific roles and access levels. Can also be used to request access to the document when the user doesn't have editor or workspace manager permissions. **Authorization**: Requires document editor or workspace manager permissions, unless `requestPermission` is true. **Parameters**: Use `requestPermission` to indicate the user is requesting access to the resource. **Roles**: Supports editor and viewer roles. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml post /organizations/{organizationName}/workspaces/{workspaceName}/documents/{documentPath}/permissions openapi: 3.1.0 info: title: Credible Admin API description: > The Credible Admin API is a comprehensive REST API that empowers organizations to manage their Malloy data modeling ecosystem with enterprise-grade security and governance. This API provides programmatic access to all administrative functions, enabling seamless integration with existing workflows and automation systems. ## Key Features - **Organization Management**: Create and manage organizations with fine-grained access controls - **Project & Package Lifecycle**: Full CRUD operations for projects, packages, and versions - **Connection Management**: Secure database connection configuration and management - **Permission Management**: Granular role-based access control (RBAC) at organization, project, package, workspace, and document levels - **Workspace Management**: Collaborative workspaces for data modeling and analysis - **User & Group Management**: Comprehensive user administration with group-based permissions ## Resource Hierarchy The API follows a hierarchical resource structure with fine-grained permission management at each level: ``` Organizations ├── Permissions ├── Projects │ ├── Permissions │ ├── Packages │ │ ├── Permissions │ │ └── Versions │ └── Connections ├── Workspaces │ ├── Permissions │ └── Documents │ └── Permissions └── Groups ├── Permissions └── Members System-Level Resources: ├── Users ├── System Permissions └── Demo Operations ``` ## Authentication & Authorization All API endpoints require proper authentication. The API implements fine-grained authorization using role-based permissions: - **Admin**: Full access to all resources within scope - **Modeler**: Can create and modify data models and packages - **Viewer**: Read-only access to resources - **Manager**: Workspace management capabilities - **Editor**: Document editing permissions ## Rate Limiting & Best Practices - API requests are rate-limited to ensure system stability - Implement proper error handling and retry logic - Cache responses when appropriate to reduce API calls ## Support & Documentation For additional support, examples, and integration guides, visit our developer documentation or contact our support team. version: v0 contact: name: Credible Support email: support@credibledata.com url: https://credibledata.com/support license: name: Proprietary url: https://credibledata.com/license termsOfService: https://credibledata.com/terms servers: - url: https://{organization}.admin.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: organizations description: >- Organization management operations for creating, updating, and managing organizational entities - name: organizationPermissions description: >- Fine-grained permission management for organizations, including role assignments and access controls - name: projects description: >- Project lifecycle management including creation, configuration, and deletion of data modeling projects - name: projectPermissions description: >- Permission management for projects, controlling access to project resources and capabilities - name: packages description: >- Package management for Malloy data models, including versioning, publishing, and distribution - name: packagePermissions description: >- Access control for packages, managing who can view, modify, or publish package versions - name: versions description: >- Version management for packages, including archiving, status updates, and lifecycle management - name: connections description: >- Database connection management for secure data source configuration and access - name: workspaces description: >- Collaborative workspace management for team-based data modeling and analysis - name: workspacePermissions description: >- Access control for workspaces, managing who can view, manage, or collaborate in workspaces - name: documents description: >- Document management within workspaces, including workbooks, dashboards, and other content - name: documentPermissions description: >- Access control for documents, managing who can view, edit, or share document content - name: groups description: >- User group management for organizing users and managing group-based permissions - name: users description: >- User account management including creation, updates, and profile management - name: demo description: Demo and self-service operations for quick setup and testing scenarios - name: permissions description: System-level permission management for administrative functions - name: bookmarks description: >- User bookmark management for saving references to workspaces, models, and chats paths: /organizations/{organizationName}/workspaces/{workspaceName}/documents/{documentPath}/permissions: post: tags: - documentPermissions summary: Create document permission description: > Creates a new permission assignment for a user or group within the document, granting them specific roles and access levels. Can also be used to request access to the document when the user doesn't have editor or workspace manager permissions. **Authorization**: Requires document editor or workspace manager permissions, unless `requestPermission` is true. **Parameters**: Use `requestPermission` to indicate the user is requesting access to the resource. **Roles**: Supports editor and viewer roles. operationId: createDocumentPermission parameters: - name: organizationName in: path required: true description: The unique identifier of the organization schema: $ref: '#/components/schemas/IdentifierPattern' - name: workspaceName in: path required: true description: The unique identifier of the workspace schema: $ref: '#/components/schemas/IdentifierPattern' - name: documentPath in: path required: true description: The path to the document within the workspace schema: $ref: '#/components/schemas/PathPattern' - name: requestPermission in: query required: false description: Indicates that the user is requesting access to the resource schema: type: boolean default: false requestBody: content: application/json: schema: $ref: '#/components/schemas/DocumentPermission' responses: '200': description: Document permission created successfully content: application/json: schema: $ref: '#/components/schemas/DocumentPermission' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Standard identifier pattern for resource names PathPattern: type: string pattern: ^[a-zA-Z0-9_/.-]+$ description: Path pattern supporting slashes, dots, and dashes DocumentPermission: type: object description: Represents a permission assignment for a user or group within a document properties: userGroupId: $ref: '#/components/schemas/UserGroupId' permission: type: string description: The role/permission level granted to the user or group enum: - editor - viewer inheritedPermission: type: string description: The permission level inherited from parent workspace enum: - manager - viewer message: type: string description: Optional message or note about the permission assignment createdAt: type: string format: date-time description: ISO 8601 timestamp indicating when the permission was created updatedAt: type: string format: date-time description: ISO 8601 timestamp indicating when the permission was last modified UserGroupId: $ref: '#/components/schemas/UserGroupIdPattern' type: string description: > A resource identifier that uniquely identifies either a user or a group within the system. This identifier is used throughout the API for permission management and access control. **Format**: - For users: `user:{email}` or `user:{userId}` - For groups: `group:{groupName}` Error: type: object x-model-name: ModelError description: Standard error response format used across all API endpoints properties: code: type: string description: > Machine-readable error code that identifies the specific error condition. Common codes include: - `VALIDATION_ERROR`: Request validation failed - `AUTHENTICATION_REQUIRED`: Valid authentication is required - `INSUFFICIENT_PERMISSIONS`: User lacks required permissions - `RESOURCE_NOT_FOUND`: Requested resource does not exist - `CONFLICT`: Resource state conflict (e.g., duplicate name) - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `INTERNAL_ERROR`: Unexpected server error message: type: string description: Human-readable error message providing details about what went wrong UserGroupIdPattern: type: string pattern: >- ^(user:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}|group:[a-zA-Z0-9._-]+)$ description: >- User or group identifier pattern (user must be valid email address, group is standard identifier) responses: BadRequest: description: >- The request was malformed or can not be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Can not perform the operation due to insufficient permissions or the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````