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
- Open Account → API keys.
- Choose the organization the key acts for, the permissions it needs and when it expires.
- 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.
| Permission | Allows | You need it for |
|---|---|---|
datasets:write | Upload survey files and cancel unfinished uploads. | Uploading a survey |
datasets:read | Read dataset metadata. | Checking an upload |
surveyguard:write | Create projects, save check configuration and start runs. | Choosing checks, submitting a batch |
surveyguard:read | Read 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.
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
| Status | What to check |
|---|---|
| 401 | The key is missing, mistyped, expired, revoked or from another environment. Revoked keys cannot be reused. |
| 403 | The key lacks the permission this endpoint requires, or your membership or account eligibility changed. |
| 404 | The resource belongs to another organization. Resources you cannot access look missing. |
All status codes are covered in Errors and retries.