Get Permissions

POST /v2/auth/permissions/get

Get Permissions

cURL

curl --request POST \
  --url https://api.velt.dev/v2/auth/permissions/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "userIds": [
      "<string>"
    ],
    "folderIds": [
      "<string>"
    ],
    "documentIds": [
      "<string>"
    ]
  }
}
'

{
    "result": {
        "status": "success",
        "message": "User permissions retrieved successfully.",
        "data": {
            "1.1": {
                "folders": {
                    "folder2": {
                        "accessRole": "editor",
                        "accessType": "restricted"
                    }
                },
                "documents": {
                    "document1-26-may-2025-folder2": {
                        "accessRole": "viewer",
                        "accessType": "restricted"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                }
            }
        }
    }
}

Use this API to get a user’s permissions for various resources like organizations, folders, documents, etc.

• Returns permissions per user and resource. Temporary permissions include an expiresAt (Unix seconds) value.
• See the Access Control overview for concepts and detailed guidance.

Endpoint

POST https://api.velt.dev/v2/auth/permissions/get

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

data · object · required

Show properties

organizationId · string · required

The ID of the organization to query.

userIds · string[] · required

Array of user IDs to fetch permissions for.

folderIds · string[]

Optional array of folder IDs to include in the result.

documentIds · string[]

Optional array of document IDs to include in the result.

Example Request

JSON

{
  "data": {
    "organizationId": "org1",
    "documentIds": ["freestyle-comments1"],
    "userIds": ["samarth"]
  }
}

cURL

cURL

curl --location 'https://api.velt.dev/v2/auth/permissions/get' \
--header 'x-velt-api-key: apiKey' \
--header 'x-velt-auth-token: authToken' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "organizationId": "org1",
        "documentIds": [
            "freestyle-comments1"
        ],
        "userIds": [
            "samarth"
        ]
    }
}'

Response

Error responses include an errorCode field with structured error codes from the UserPermissionAccessRoleResult enum. This helps you handle permission resolution failures programmatically.

Response Schema

The response returns a nested structure with permissions per user and resource type. Each resource permission can include:

Field	Type	Description
accessRole	string	The user’s access role ("editor" or "viewer")
accessType	string	The effective access type for the resource: "public", "restricted", or "organizationPrivate". Documents inside folders inherit the folder’s accessType. Also present on PERMISSION_DENIED entries.
expiresAt	number	Unix timestamp (seconds) when temporary access expires
error	string	Human-readable error message if permission resolution failed
errorCode	string	Error code from UserPermissionAccessRoleResult enum (v4.5.4+)

Success Response

{
    "result": {
        "status": "success",
        "message": "User permissions retrieved successfully.",
        "data": {
            "1.1": {
                "folders": {
                    "folder2": {
                        "accessRole": "editor",
                        "accessType": "restricted"
                    }
                },
                "documents": {
                    "document1-26-may-2025-folder2": {
                        "accessRole": "viewer",
                        "accessType": "restricted"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                }
            }
        }
    }
}

Success Response with Context Access Info

When using Access Context for feature-level permissions, the response includes a context object with accessFields showing which context values the user has access to:

{
    "result": {
        "status": "success",
        "message": "User permissions retrieved successfully.",
        "data": {
            "user_123": {
                "documents": {
                    "document1": {
                        "accessRole": "editor",
                        "accessType": "organizationPrivate"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                },
                "context": {
                    "accessFields": ["widgetId:1", "widgetId:2", "widgetId:3"]
                }
            }
        }
    }
}

The accessFields array contains strings in the format "fieldName:value" representing each context field and value combination the user has access to.

Permission Denied

{
    "result": {
        "status": "success",
        "message": "User permissions retrieved successfully.",
        "data": {
            "1.1": {
                "documents": {
                    "document5": {
                        "error": "User does not have access to document",
                        "errorCode": "permission_denied",
                        "accessType": "restricted"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                }
            }
        }
    }
}

Error Response Examples

When a resource does not exist, is denied, or encounters an error, the response includes both an error message and an errorCode:

Resource Not Found:

{
    "error": {
        "details": {
            "1.1": {
                "documents": {
                    "document1-26-may-2025-folder222": {
                        "error": "Document does not exist",
                        "errorCode": "does_not_exist"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                }
            }
        },
        "message": "Folder or document does not exist",
        "status": "NOT_FOUND"
    }
}

API Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
    "result": {
        "status": "success",
        "message": "User permissions retrieved successfully.",
        "data": {
            "1.1": {
                "folders": {
                    "folder2": {
                        "accessRole": "editor",
                        "accessType": "restricted"
                    }
                },
                "documents": {
                    "document1-26-may-2025-folder2": {
                        "accessRole": "viewer",
                        "accessType": "restricted"
                    }
                },
                "organization": {
                    "org1": {
                        "accessRole": "editor"
                    }
                }
            }
        }
    }
}