Skip to main content

Documentation Index

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

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

ByteStack authenticates every API request using API keys. You include your key in the Authorization header of each request, and ByteStack validates it before executing the query. This page explains how to create keys, which scopes are available, how to include keys in requests across different languages, and how to respond to authentication errors.

​
Creating an API key

To generate a new API key:
  1. Open Settings → API Keys in the ByteStack dashboard.
  2. Click New Key.
  3. Enter a descriptive name for the key (for example, production, development, or ci-pipeline).
  4. Select the scopes the key should have (see Key scopes below).
  5. Click Create and copy the key.
The full key value is only shown once, immediately after creation. Copy it to a secure location before closing the dialog. If you lose the key, you must rotate it.
Never commit API keys to source control. Use environment variables, a secrets manager, or a CI/CD secrets store to inject keys at runtime.

​
Including keys in requests

Pass your API key as a Bearer token in the Authorization header of every request. 
curl -X POST https://api.bytestack.dev/v1/queries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Mentions of Acme on X this week", "sources": ["x"]}'

​
Key scopes

Each API key is issued with one or more scopes that control what it can do. Assign only the scopes a key actually needs.
ScopeWhat it allows
readFetch query results, retrieve job status, and list sources
writeSubmit new queries, create and manage scheduled jobs
adminManage API keys, update billing settings, and configure integrations
Use separate keys for separate environments — for example, one write key for your production pipeline and one read key for your analytics dashboard. This limits the blast radius if a key is compromised.

​
Rotating keys

If a key is compromised or you want to cycle credentials as part of a security policy, rotate it from Settings → API Keys:
  1. Generate a new key with the same scopes as the key you are replacing.
  2. Update your application or secrets manager with the new key.
  3. Verify that requests succeed with the new key.
  4. Revoke the old key by clicking Revoke next to it in the key list.
Revoking a key takes effect immediately. Any in-flight requests using the revoked key will receive a 401 Unauthorized response.

​
Authentication errors

HTTP statusMeaningCommon cause
401 UnauthorizedThe key is missing, malformed, or has been revokedMissing Authorization header, typo in the key, or key revoked
403 ForbiddenThe key is valid but lacks the required scopeUsing a read-scoped key to submit a new query
When you receive a 401, check that the Authorization header is formatted as Bearer YOUR_API_KEY (note the space after Bearer) and that the key has not been revoked. When you receive a 403, review the scopes assigned to the key and generate a new key with the correct scope if needed.
A 402 Payment Required response means your account has an unpaid balance. ByteStack provides a 7-day grace period for failed charges. Resolve billing in Settings → Plans & Billing to restore full API access.