How to Manage API Keys in RuleSync

API Keys: Programmatic Access to RuleSync

RuleSync API keys: authenticate non-interactive access to the RuleSync API. Use cases: CI/CD pipelines (rulesync pull --check runs in GitHub Actions, GitLab CI, or any pipeline without interactive login), automation scripts (scheduled rule pulls, compliance reporting, bulk operations), and third-party integrations (custom tooling that reads or updates rulesets programmatically). API keys: replace the interactive login flow for scenarios where a human is not present to authenticate.

Key types: organization keys (access all projects and rulesets in the organization — for admin automation), project keys (access a single project — for per-project CI/CD pipelines), and read-only keys (can pull rulesets but cannot modify — for CI checks that only verify rules are current). The principle of least privilege: use the most restricted key type that meets the need. A CI pipeline that only checks rule freshness: needs a read-only key, not an organization admin key.

Security: API keys are secrets. They grant access to your organization's AI rules and configuration. Treat them with the same security as any other API credential: store in secrets managers (GitHub Secrets, GitLab CI Variables, AWS Secrets Manager), never commit to repositories, rotate regularly, and revoke immediately when compromised or no longer needed.

Step 1: Creating API Keys

From the dashboard: Settings → API Keys → Create Key. Enter: key name (descriptive — 'GitHub Actions CI - Frontend Repo'), scope (organization, project, or read-only), and expiration (optional — recommended for temporary access, e.g., contractor engagements). The dashboard: generates the key and displays it once. Copy the key immediately — it cannot be retrieved after the dialog is closed. Store in your secrets manager right away.

For CI/CD: create a read-only project key. Name it after the pipeline: 'GHA CI - my-app - read-only'. Scope: the specific project. Permission: read-only (the pipeline only runs rulesync pull --check, which reads but does not modify). Store the key as: RULESYNC_API_KEY in your CI platform's secrets (GitHub → Settings → Secrets → Actions, GitLab → Settings → CI/CD → Variables).

For automation scripts: create an organization key with appropriate permissions. If the script only reads (pulls rules, generates reports): read-only. If the script modifies (updates rulesets, changes assignments): read-write. Name: 'Automation Script - Weekly Rule Sync'. Include the purpose in the name so future admins understand what the key is for. AI rule: 'Descriptive key names save time when auditing. A key named 'test123': nobody knows what it does. A key named 'GHA CI - frontend - read-only': self-documenting.'

Step 2: Rotation and Revocation

Rotation schedule: rotate API keys every 90 days for security. The rotation process: create a new key → update the secret in CI/CD (or wherever the key is stored) → verify the new key works (run a test pull) → revoke the old key. The overlap period (both keys active): should be short (1-2 days) to allow updating all systems that use the key. AI rule: 'Quarterly rotation (90 days): balances security with operational overhead. Annual rotation: too infrequent (compromised keys have long exposure). Monthly: too frequent (operational burden).'

Revocation: Settings → API Keys → [key name] → Revoke. Immediate effect: any request using the revoked key returns 401 Unauthorized. The CI pipeline: fails on the next run (expected — update the key before the next scheduled run). Revoke when: the key is compromised (immediately), an employee who had access leaves the organization (revoke all keys they might have accessed), or the key's purpose no longer exists (the project was decommissioned).

Key audit: Settings → API Keys shows: all active keys, their scopes, last-used date, and creation date. Keys not used in 90+ days: candidates for revocation (the automation they served may no longer be running). Keys with organization-wide scope: review quarterly to ensure the broad access is still justified. AI rule: 'Monthly audit: check for unused keys (last used > 90 days), over-scoped keys (org-wide when project-scoped would suffice), and expired keys that were not cleaned up.'

Step 3: Using API Keys in CI/CD Pipelines

GitHub Actions: store the key as a repository secret (RULESYNC_API_KEY). In the workflow: env: RULESYNC_API_KEY: ${{ secrets.RULESYNC_API_KEY }}. The CLI: detects the environment variable automatically. No explicit --api-key flag needed. The secret: masked in logs (GitHub replaces the value with *** in any log output).

GitLab CI: store as a CI/CD variable (Settings → CI/CD → Variables). Mark as: masked (hidden in job logs) and protected (only available on protected branches — prevents exposure in feature branch jobs from untrusted contributors). In .gitlab-ci.yml: the variable is available as $RULESYNC_API_KEY automatically.

Other CI platforms: set RULESYNC_API_KEY as an environment variable using the platform's secrets mechanism. Jenkins: credentials store. CircleCI: project environment variables. Azure DevOps: pipeline variables with secret flag. The RuleSync CLI: reads RULESYNC_API_KEY from the environment on every platform. No platform-specific CLI configuration needed. AI rule: 'One environment variable (RULESYNC_API_KEY) works on every CI platform. Store it in the platform's secrets manager. The CLI reads it automatically.'

API Key Management Summary

Complete RuleSync API key management guide.

• Key types: organization (admin), project (per-repo), read-only (CI checks). Use least privilege
• Create: dashboard → Settings → API Keys. Copy immediately — shown once only
• CI keys: read-only, project-scoped. Named after the pipeline and repository
• Storage: CI platform secrets (GitHub Secrets, GitLab Variables). Never in code or config files
• Rotation: every 90 days. Create new → update secrets → verify → revoke old
• Revocation: immediate effect. Revoke on compromise, employee departure, or project decommission
• Audit: monthly review of unused keys (90+ days), over-scoped keys, and expired keys
• CI integration: RULESYNC_API_KEY env var. Masked in logs. Works on all CI platforms