API keys

An API key lets a script act for one organization, with only the permissions you give it. Create it once, store it as a secret and send it with every request.

Create a key

  1. Open Account → API keys.
  2. Choose the organization the key acts for, the permissions it needs and when it expires.
  3. Copy the secret. It is shown once; if you lose it, rotate the key to get a new one.
Store the secret in a secret manager or an environment variable. Never put it in browser code, a URL or source control.

Choose permissions

Give each key only what its job needs. A dashboard that only shows findings needs surveyguard:read and nothing else.

API key permissions
PermissionAllowsYou need it for
datasets:writeUpload survey files and cancel unfinished uploads.Uploading a survey
datasets:readRead dataset metadata.Checking an upload
surveyguard:writeCreate projects, save check configuration and start runs.Choosing checks, submitting a batch
surveyguard:readRead configuration, progress and results.Polling and reading results

Your organization membership and account eligibility still apply. A key never grants more than you can do yourself.

Send the key

Add an Authorization: Bearer YOUR_API_KEY header to every API request. The examples in these docs read the key and the base URL from environment variables.

Environment setup
export CM_API_BASE="https://dev.crowdmines.ai/api/customer/v1"
# Set CM_API_KEY securely in your environment; do not paste it into source code.
# Use the same environment where you created your key.
export CM_PROJECT_ID="YOUR_PROJECT_ID"
export CM_BATCH_REQUEST_ID="YOUR_UNIQUE_BATCH_ID"

The example targets dev. Use the Crowdmines environment where you created the key; a key from one environment does not work on another.

Storage links take no key. Upload and result download links are already signed. Sending your API key to them exposes it to a system that does not need it.

Expiry, rotation and revoking

Expiry
You choose 1–365 days. An expired key answers 401.
Active keys
Up to 20 at a time.
Rotate
Issues a new secret and invalidates the previous one immediately. Update your secret store first if you need no downtime.
Revoke
Blocks all future calls. Jobs the API already accepted keep running.

When a key is refused

Key errors and fixes
StatusWhat to check
401The key is missing, mistyped, expired, revoked or from another environment. Revoked keys cannot be reused.
403The key lacks the permission this endpoint requires, or your membership or account eligibility changed.
404The resource belongs to another organization. Resources you cannot access look missing.

All status codes are covered in Errors and retries.