> ## 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 - **Environment & Package Lifecycle**: Full CRUD operations for environments, packages, and versions - **Connection Management**: Secure database connection configuration and management - **Permission Management**: Granular role-based access control (RBAC) at organization, environment, 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 ├── Environments │ ├── 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: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: environmentPermissions description: >- Permission management for environments, controlling access to environment 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: materializations description: >- Malloy Persistence materializations (per-version serving anchors for persisted sources) - name: indexes description: >- Malloy Persistence dimensional search indexes (per-version serving anchors for indexed dimensions) - name: runs description: >- Malloy Persistence build/refresh runs — one package-level build event carrying typed units (materialized sources + built indexes) - 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 - name: attributes description: Trusted user attributes for fine-grain (row/column-level) access control - name: invites description: >- Organization-creation invite tokens. A super-admin mints tokens one per call (call `POST /invites` repeatedly to populate an outreach campaign); each token can be redeemed once by an authenticated user to create a new organization on the fly. 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/WorkspaceNamePattern' - name: documentPath in: path required: true description: The path to the document within the workspace schema: $ref: '#/components/schemas/DocumentPathPattern' - 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 WorkspaceNamePattern: type: string pattern: ^(?!.*\*)(?!.*[/]).{1,63}$ description: >- Workspace name pattern. Allows any character except `/` (would split the FGA resource path — see ResourceIdentifier.parseFromFga) and `*` (FGA wildcard). 1-63 chars. DocumentPathPattern: type: string maxLength: 255 pattern: ^(?!.*\.\.)[a-zA-Z0-9_/. \-&:,'+?!()$^–—]+$ description: >- Document path. Permits alphanumerics, spaces, ASCII hyphen, Unicode en-dash/em-dash (U+2013/U+2014), and common title punctuation (& : , ' + ? ! ( ) $ ^). Bans path traversal (..). Length capped at 255 to match the underlying varchar(255) storage column. % is deliberately excluded because @InitBinder decodes %2F → / in path variables to fix encoded-slash routing, which would collide with any path that legitimately contained '%2F'. 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. Clients should branch on `code`, not on the human-readable `message` — the message text is informational and may change over time. Generic codes (may appear on any endpoint): - `VALIDATION_ERROR`: Request body or path/query parameter failed validation - `AUTHENTICATION_REQUIRED`: Valid authentication is required - `INSUFFICIENT_PERMISSIONS`: User lacks required permissions - `RESOURCE_NOT_FOUND`: Requested resource does not exist - `CONFLICT`: Generic resource state conflict (used when no more specific code applies) - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `INTERNAL_ERROR`: Unexpected server error Endpoint-specific codes used by the signup / invites flow: - `ORGANIZATION_NAME_TAKEN`: 409 on `POST /organizations` — the requested org name (URL slug) is already in use. Retry with a different name. - `ORGANIZATION_NAME_RESERVED`: 409 on `POST /organizations` — the requested org name collides with a platform subdomain (e.g. `signup`, `admin`, `data`, `login`) and cannot be claimed. Retry with a different name. - `INVITE_ALREADY_CONSUMED`: 409 on `POST /organizations` — the supplied invite token has already been redeemed into an existing organization. Retry will not help; the token is dead. - `INVITE_ALREADY_CONSUMED_REVOKE`: 409 on `DELETE /invites/{token}` — consumed invites are preserved for audit and cannot be revoked. - `INVITE_INVALID`: 400 on `POST /organizations` — the supplied invite token is malformed or unknown. - `INVITE_EXPIRED`: 400 on `POST /organizations` — the supplied invite token is past its `expiresAt`. - `INVITE_EMAIL_MISMATCH`: 403 on `POST /organizations` — the invite is bound to a different email address than the caller. 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 ````