Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt

Use this file to discover all available pages before exploring further.

Directory grants are the permission records that control access to a directory. Each grant assigns a single permission level to a principal — an organization, user, or API key. When a request arrives, Orbit checks whether the caller’s principal matches any grant on the requested directory. You use the endpoints below to inspect and modify the grant list for any directory your credentials can manage.
Organization admins have implicit access to all directories within their organization and do not require explicit grants.For developer API key directory search, the key must be an organization API key (not a personal key) and must match an organization or api_key grant with search or manage permission on the target directory. Personal API keys are always rejected for directory search.

​
Permissions

Allows the principal to upload source data into this directory, including CSV files and connection imports.
Full administrative control. A principal with manage permission can update directory metadata, manage sources, create and delete grants, and run searches. Grants search and upload capabilities as well.

​
Grant principals

Principal typeWhat it grants access to
organizationAll users and API keys across the entire organization.
userOne specific organization member.
api_keyOne specific organization API key.

​
List grants

GET /v2/organizations/:organizationId/directories/:directoryId/grants Returns all grants currently assigned to the specified directory.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory whose grants you want to list.
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/grants" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

​
Create a grant

POST /v2/organizations/:organizationId/directories/:directoryId/grants Assigns a permission to a principal on the specified directory. If the principal already has a grant on this directory, the existing grant is updated.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory to grant access on.

​
Request body

​
principal_type
string
required
The type of principal receiving the grant. One of organization, user, or api_key.
​
principal_id
string
required
The UUID of the principal — the organization ID, user ID, or API key ID depending on principal_type.
​
permission
string
required
The permission to assign. One of search, upload, or manage.
curl -X POST "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/grants" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "api_key",
    "principal_id": "API_KEY_UUID",
    "permission": "search"
  }'

​
Delete a grant

DELETE /v2/organizations/:organizationId/directories/:directoryId/grants/:grantId Removes a grant from a directory. The principal immediately loses the associated permission.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory.
​
grantId
string
required
The UUID of the grant to delete.