Documentation
Teams & Enterprise
API Keys & Management

API Keys & Management

How to create, manage, and configure credentials for Spark CLI across your team.

Creating API keys

API keys are created in the Spark dashboard at spark.memco.ai/dashboard (opens in a new tab).

  1. Navigate to Settings > API Keys
  2. Click Create Key
  3. Add a descriptive name (e.g., "CI/CD pipeline", "staging environment", "developer-jane")
  4. Copy the key immediately — it won't be shown again

API keys follow the format sk_ followed by a random string:

sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key rotation

Rotate keys regularly and whenever a team member leaves:

  1. Create a new key in the dashboard
  2. Update all environments using the old key
  3. Verify the new key works in each environment
  4. Revoke the old key in the dashboard
⚠️

Revoke keys immediately when a team member leaves or when a key may have been exposed. You can revoke keys from the dashboard without affecting other active keys.

Environment variable setup for CI/CD

Set the SPARK_API_KEY environment variable in your CI/CD platform. The CLI automatically uses this variable when present — no login step required.

Add SPARK_API_KEY as a repository secret, then reference it in your workflow:

# .github/workflows/build.yml
steps:
  - name: Query Spark for known issues
    env:
      SPARK_API_KEY: ${{ secrets.SPARK_API_KEY }}
    run: spark query "build failure ${{ job.status }}" --tag domain:deployment

spark query returns compact JSON by default — perfect for piping into a CI step. Use --pretty (placed before the subcommand) only when a human is reading the output.

API keys set via environment variables are never written to disk by Spark.

Per-project credentials

Use spark login --local to store credentials scoped to a specific project:

cd your-project
spark login --local

This creates a ./.spark/settings.json file in your project root with project-level credentials.

🚫

Add .spark/ to your .gitignore to prevent accidentally committing credentials to version control.

echo ".spark/" >> .gitignore

Global vs. project-level configuration

ScopeFile locationCreated by
User-global~/.spark/settings.jsonspark login
Project./.spark/settings.jsonspark login --local

Project-level credentials are checked before user-global credentials.

Configuration resolution order

When Spark needs a credential, it checks these sources in order. The first value found wins:

1. CLI flag           →  spark --api-key sk_... query "..."
2. Environment var    →  SPARK_API_KEY=sk_...
3. OAuth tokens       →  ./.spark/settings.json (local) then ~/.spark/settings.json (global)
4. Legacy API key     →  apiKey field in settings.json (back-compat)

This means:

  • --api-key (a global flag — placed before the subcommand) always wins
  • SPARK_API_KEY overrides any stored OAuth tokens
  • Project-local settings override user-global settings
  • The legacy apiKey field in settings.json is the lowest-priority fallback

Best practices

  • Use OAuth for developer machines, API keys for CI/CD. OAuth tokens auto-refresh and don't require manual rotation.
  • Use separate keys per environment (staging, production, CI) so you can revoke one without affecting others.
  • Rotate keys quarterly as a baseline, and immediately after any team member departure.
  • Never commit keys to version control. Use environment variables or your CI's secrets manager.
  • Keep .spark/ in .gitignore in every project that uses spark login --local.
Onboarding GuideOverview