Appearance
Authentication & Security
Use the API address and key supplied for your deployment. Every REST request includes x-api-key; gRPC clients send the same key as metadata.
http
GET /collection HTTP/1.1
Host: YOUR_API_HOST
x-api-key: YOUR_API_KEY
api-version: 1.0API versioning
Select REST API version 1.0 with either api-version or x-api-version. Send one version header consistently. Public MAS uses its documented /v1 paths; follow its authentication contract.
API key rights
Rights are flags. Endpoint tables list alternatives: Read or Admin means either right authorizes the operation. Keys remain scoped to their subscription. Administrative rights do not grant access to another subscription's data.
| Right | Value | Purpose |
|---|---|---|
Read | 1 | Search, list collections, and read task state. |
Write | 2 | Ingest documents, deploy packages, and create jobs. |
Admin | 4 | Administrative operations, including collection deletion and clearing. |
Statistic | 8 | Read statistics on endpoints that accept this right. |
MasAgent | 128 | Customer agent operations supported by Public MAS. |
MasAdmin | 256 | Public MAS operations that explicitly require administrative access. |
Consult the Public MAS reference for endpoint-specific ownership and permission rules. Grant only the rights an integration needs. A search application normally needs Read; ingestion needs Write or Admin.
Handling authentication failures
Treat 401 as an authentication failure and 403 as a permission failure. Verify the deployment address, key, subscription, and endpoint rights before retrying. Keep keys out of browser-delivered code, URLs, source control, and logs. Store them in secret configuration and rotate them through your administrator.
Webhook signatures use separate credentials. Follow the webhook provider contract when sending signed events.
Next: Public API Reference