API keys let your code authenticate to Vulgate just like the web app does. Each key is scoped to a single team / Organization and inherits its permissions.

Generate a new key

  1. Open the Vulgate app.
  2. From the sidebar, choose Settings → API.
  3. Click Create a new API key.
  4. Give the key a name that explains what it’s for (“Production”, “CI/CD”, “Local dev”). Names help you spot and revoke the right key later.
  5. Click Create.

Vulgate shows the key value once — copy it immediately. We never display it again; the only recovery is to generate a new one.

Storing the key

Never commit a key to version control. The two safe patterns are:

  • Environment variable in your shell or CI:
export VULGATE_API_KEY=...
  • .env file loaded at runtime (and .env listed in your .gitignore):
VULGATE_API_KEY=...

Then read it from your code:

import os
api_key = os.environ["VULGATE_API_KEY"]
const apiKey = process.env.VULGATE_API_KEY!;

Using the key

Every request needs the key in the Authorization header:

curl https://vulgate.ai/api/search \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

List existing keys

The Settings → API page shows every key created for the current team, with the key’s name and creation date.

Delete a key

  1. Open Settings → API.
  2. Find the key in the list.
  3. Click Delete API key.
  4. Confirm.

Deletion takes effect within seconds. Any request using a deleted key gets HTTP 401.

Key best practices

  • One key per app. Mixing keys across apps means you can’t revoke one without breaking the other.
  • Use clear names. They cost nothing and save you in an incident.
  • Rotate periodically. Generate a new key, deploy it, then delete the old one.
  • Keep keys out of logs. Configure your logging library to redact Authorization headers.

What scope does a key have?

Each API key is scoped to a single team and carries the permissions of the team owner. That means an API key can do whatever the team’s Owner can do — including uploading, searching, and reading documents in that team.