API Keys

API keys authenticate CI pipelines and programmatic access to pxdiff. Each key is scoped to a single project and prefixed with pxd_.

Creating an API key

1. Open your project in the pxdiff dashboard.
2. Go to Project Settings.
3. Under API Keys, enter a name (e.g., “GitHub Actions”) and click Create.
4. Copy the key immediately — it’s only shown once.

The key looks like pxd_ followed by a random string:

pxd_abc123def456...

Using an API key in CI

Set the PXDIFF_API_KEY environment variable. The CLI, SDK, and all plugins read it automatically — no extra configuration needed.

GitHub Actions

Add the key as a repository secret (PXDIFF_API_KEY), then expose it in your workflow:

env:
  PXDIFF_API_KEY: ${{ secrets.PXDIFF_API_KEY }}

Other CI providers

Set PXDIFF_API_KEY as a secret environment variable in your provider’s settings. pxdiff doesn’t need any provider-specific setup.

Key scoping

• Each API key belongs to one project. It grants access to captures, diffs, baselines, and snapshots within that project.
• A project can have multiple keys — useful for separating access per CI provider, workflow, or team member.
• Keys cannot access other projects in your organization. Create separate keys for each project.

Rotating a key

To rotate without downtime:

1. Create a new key in Project Settings.
2. Update the CI secret to use the new key.
3. Verify a CI run succeeds with the new key.
4. Delete the old key in Project Settings.

Deleting a key

Click the delete button next to any key in Project Settings. Deletion is immediate — any CI pipeline still using the deleted key will fail authentication on its next run.

Security best practices

• Never commit keys to source control. Use your CI provider’s secret management (GitHub Secrets, GitLab CI variables, etc.).
• Use descriptive names. Name keys after where they’re used (e.g., “GitHub Actions - main repo”) so you know what breaks if you delete one.
• Rotate keys periodically. If a key may have been exposed, rotate it immediately.
• Use one key per concern. Separate keys for different CI workflows make revocation surgical — you can revoke one without breaking others.
• Check last-used dates. The Project Settings page shows when each key was last used. Delete keys that haven’t been used recently.