Collection Permissions and Limits

The specific risk of knowledge bases

An enterprise knowledge base is never trivial: internal notes, confidential reports, contracts under negotiation. If access controls fail, you don’t just leak a single file—you expose the entire base, complete with a search engine to find what matters. xAI’s permission system mitigates this risk by separating rights, while quotas govern usage and billing.

Two keys, two roles

The xAI ecosystem relies on two credentials for distinct scopes:

This separation applies the principle of least privilege concretely. A developer connecting a support chatbot to your base needs to query the collection, never delete it. By giving them only the standard key, a script error or compromised key cannot destroy an index built over months.

The AddFileToCollection permission

A Management API Key is not all-powerful by default. Its rights are explicit, and the most critical one for collections is AddFileToCollection. Without it, you can create and list collections but cannot add a single document—a confusing situation, since everything seems to work until ingestion. Generating a correct key involves four steps:

1. Log in to the xAI console
2. Create a new Management API Key
3. Enable the AddFileToCollection permission
4. Store the key securely: environment variable or secrets manager

When the permission is missing, the API is explicit and returns a 403:

{
  "error": {
    "message": "Insufficient permissions",
    "type": "permission_error",
    "code": 403
  }
}

Your first step should be to check the key’s rights in the console rather than suspecting the request, whose syntax has nothing to do with the rejection.

Quotas and their costs

Three caps govern storage per account: 100,000 files total, 100 GB of cumulative capacity, and 100 MB per individual file in collections—more than double the 48 MB allowed by the Files API alone, letting you include documents you couldn’t send as direct attachments.

On the billing side, two lines stand out: Collections Search is billed at $2.50 per 1,000 search calls, while File Attachments cost $10 per 1,000 calls. The difference is significant and weighs on architectural choices. Under heavy usage, querying an indexed collection costs significantly less than re-attaching the same document with every question.

If your needs exceed these quotas, xAI support can grant an increase. Prepare your request with figures—target file count, total volume, expected search frequency—rather than a vague estimate. This speeds up processing of the request.

Isolate, rotate, monitor

The first practice concerns keys. Assign different keys to each environment, so a development script can never touch the production base. Never give a Management key to a service whose only need is search. And rotate these keys regularly, especially after a collaborator with access to secrets leaves.

The second concerns structure. Rather than a single collection where public documentation and contracts coexist, separate your bases by confidentiality level: a “public” base for open documentation, an “internal” base for company documents, and a “confidential” base for sensitive data. Each service then receives only the access it needs, and the question “can this chatbot cite a contract?” is answered by design.

The third is monitoring. Check your consumption in the xAI console, set an alert on any unexpected rise in search volume—often the first sign of a runaway loop—and keep a written record of which services access which collections.

One file, multiple collections

This isolation does not require duplicating your documents, since the same file can belong to multiple collections. A technical report thus appears in “product-documentation” for the technical team, in “quarterly-reports” for management, and in “support-base” for customer service. It is stored only once, counts only once toward your quotas, and remains searchable in all three contexts—thematic views by audience, without divergent copies.

Key takeaways

• Two distinct API keys: standard for usage, Management for administration
• The AddFileToCollection permission is essential to populate collections
• Limits are 100,000 files, 100 GB, and 100 MB per file
• Separate your collections by confidentiality level
• A file can belong to multiple collections without duplication