Skip to main content

API Keys

API keys authenticate programmatic access to VectorAmp datasets, ingestion jobs, sources, search, and intelligence endpoints.

Current format

VectorAmp API keys use the format vsk_<64hex>. Pass keys with the X-API-Key header for REST calls, SDKs, CLI automation, and MCP headless workflows.

When to use an API key​

Use API keys for server-side and automation contexts:

  • backend services calling the REST API,
  • ingestion jobs and CI workflows,
  • CLI scripts,
  • SDK-based services,
  • MCP servers running in headless or agent environments.

Do not expose API keys in browser JavaScript, mobile apps, screenshots, logs, or user-editable configuration.

Create a key in the dashboard​

Open Settings → API Keys in VectorAmp to:

  • view active keys,
  • create a key for an environment or service,
  • copy the key once at creation time,
  • revoke keys that are no longer needed.

Use a key with REST​

curl https://api.vectoramp.com/datasets \
  -H "X-API-Key: vsk_<64hex>"

X-API-Key is the recommended header. The gateway resolves the organization from the key, so client requests do not need to pass an organization ID.

Use a key with the CLI​

export VECTORAMP_API_KEY=vsk_<64hex>
export VECTORAMP_BASE_URL=https://api.vectoramp.com

Or store it in the local CLI config:

vectoramp config set --api-key vsk_<64hex>
vectoramp config set --base-url https://api.vectoramp.com

Use a key with SDKs​

from vectoramp import VectorAmp

client = VectorAmp(api_key="vsk_<64hex>")
import { VectorAmp } from '@vectoramp/vectoramp';

const client = new VectorAmp({ apiKey: process.env.VECTORAMP_API_KEY });

Environment strategy​

Create separate keys for each environment and service.

Key nameExample use
production-apiCustomer-facing backend search and intelligence calls.
production-ingestScheduled source ingestion and indexing jobs.
staging-apiStaging app validation.
developer-localLocal integration testing.
ci-docs-smoke-testAutomated docs or API smoke tests.

Separating keys lets you revoke or rotate one workflow without breaking the rest of the platform.

Rotation checklist​

  1. Create a replacement key.
  2. Deploy the new key through your secrets manager.
  3. Confirm traffic succeeds with the new key.
  4. Revoke the old key.
  5. Check logs and dashboards for unexpected 401 errors.

Security best practices​

  • Store keys in a secrets manager or environment variable.
  • Never commit keys to source control.
  • Never embed keys in client-side applications.
  • Rotate keys after demos, screenshots, log leaks, or personnel changes.
  • Use separate keys for production, staging, development, ingestion, and CI.
  • Revoke keys immediately when a service is retired.

Troubleshooting​

SymptomCheck
401 UnauthorizedConfirm the key is active, copied correctly, and sent as X-API-Key.
Requests hit the wrong environmentCheck VECTORAMP_BASE_URL and deployment secrets.
A local CLI command works but production failsCompare key value, base URL, and dataset ID between environments.
A revoked key still appears in an appRedeploy the service or refresh the secret mount/cache.