Managing API Keys

API keys let integrations (CI pipelines, Terraform, scripts) talk to the DataRecs API without interactive logins. Keys inherit the tenant or workspace roles you assign, so they should be created deliberately and rotated regularly.

Permissions and scope

• API keys are created at the tenant level. You decide which platform roles (Owner/Admin) or workspace roles the key should impersonate.
• Keys are envelope-encrypted and stored in Vault. You will only see the plain value once—copy it somewhere safe.
• Each key has metadata: name, description, created_by, last_used_at, and whether it’s enabled.

Create an API key

Console

1. Navigate to Access management → API Keys.
2. Click New API Key.
3. Provide a Name and optional Description.
4. Choose the Role the key should assume (e.g. admin, workspace_admin).
5. Optionally restrict the key to a specific workspace.
6. Click Generate.
7. Copy the generated key value and store it in your password manager / secret store.

CLI

datarecs api-key create \
  --name "ci-deploy" \
  --role admin \
  --workspace workspace_123 \
  --description "Used by GitHub Actions"

The CLI prints the key once. Use --json if you want structured output for scripts.

Terraform

resource "datarecs_api_key" "ci" {
  name        = "ci-deploy"
  role        = "admin"
  workspace_id = datarecs_workspace.production.id
  description = "GitHub Actions deploys"
}

tofu plan
tofu apply

REST API

curl -X POST https://api.datarecs.com/v1/api-keys \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "description": "GitHub Actions",
    "role": "admin",
    "workspace_id": "workspace_123"
  }'

Rotating a key

1. Create a new key following the steps above.
2. Update every system that used the old key (CI, Terraform, scripts) to use the new value.
3. Once the new key is live, disable and then delete the old key.

You can disable a key temporarily to test without deleting it:

datarecs api-key disable --api-key-id key_abc
datarecs api-key enable --api-key-id key_abc

Viewing usage & auditing

• The API Keys page shows last used at and created by metadata.
• datarecs api-key list prints the same metadata for scripting.
• Audit logs record every create/update/delete and every request authenticated with a key.

Revoking a compromised key

1. Disable or delete the key immediately via Console/CLI/API.
2. Review audit logs to understand what actions were taken.
3. Create replacement keys if necessary.
4. Consider rotating other credentials if the key had broad access.

Best practices

• Prefer least privilege: assign the narrowest role possible.
• Store keys in a secret manager (Vault, AWS Secrets Manager, GitHub Actions secrets). Never hard-code them.
• Rotate keys on a schedule (e.g. every 90 days) or whenever staff changes occur.
• Use different keys for different automation contexts so you can revoke/review independently.
• Monitor usage: stale keys are a risk—delete keys with no activity.

Troubleshooting

Issue	Resolution
401 Unauthorized	Ensure you copied the key exactly. Keys are case-sensitive. Verify it hasn’t been disabled.
Cannot create key	You need the create_api_key permission (Owner/Admin). Ask your tenant admin.
Exceeded key limit	Delete unused keys or contact support to raise the quota.
Forgotten key value	Generate a new key; existing values cannot be retrieved once generated.