Managing API Keys

API keys let integrations (CI pipelines, Terraform, scripts) talk to the DataRecs API without interactive logins. A key carries a set of scopes and permissions.

Permissions and scope — not roles

• permissions is an explicit list of permission strings — the same lowercase snake_case catalog used elsewhere in the platform (e.g. list_jobs, run_job, view_job_results, list_connections). There is no single admin role to assign; you list exactly what the key can do.
• scopes controls which workspaces the key can act in: ["*"] means tenant-wide (every workspace); a list of workspace IDs restricts the key to just those.
• A handful of sensitive permissions can never be granted to an API key, no matter who creates it: create_api_key, update_api_key, delete_api_key, impersonate_user, update_billing_method, modify_licences. These require a human in the Console.
• Keys are envelope-encrypted at rest in OpenBao. You will only see the plain key value once, at creation — copy it somewhere safe.
• Each key has: name, optional description, scopes, permissions, optional expiry_time, metadata, a non-secret prefix, and last_used_at.
• Creating a key requires the create_api_key permission, and you can only grant permissions you already hold yourself.

Create an API key

There is currently no CLI topic for API keys — create and manage them from the Console, the REST API, or Terraform.

Console

1. Navigate to Access management → API Keys.
2. Click New API Key.
3. Provide a Name and optional Description.
4. Select the permissions the key needs and the scopes (workspace IDs, or tenant-wide) it can act within.
5. Click Generate.
6. Copy the generated key value and store it in your secret manager — it is shown only once.

Terraform

resource "datarecs_api_key" "ci" {
  name        = "ci-deploy"
  description = "GitHub Actions deploys"
  scopes      = [datarecs_workspace.production.id]
  permissions = ["view_job", "run_job", "view_job_results"]
  expiry_time = "2027-01-01T00:00:00Z"
}

tofu plan
tofu apply

The cleartext key is a sensitive computed attribute returned only on creation. scopes and permissions both RequiresReplace — narrowing/widening access means a new key, not an in-place update. datarecs_api_key has no role or workspace_id argument.

REST API

curl -X POST https://api.datarecs.io/api-keys \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "description": "GitHub Actions deploys",
    "metadata": {},
    "scopes": ["<workspace-id>"],
    "permissions": ["view_job", "run_job", "view_job_results"]
  }'

The response contains the stored key metadata and cleartextApiKey — the only time the full key value is returned. Its format is dtrcs:<tenant_id>:<key_id>:<secret>.

API endpoints

Method	Path	Description
GET	/api-keys	List your keys (metadata only)
GET	/api-keys/{id}	Get one key’s metadata
POST	/api-keys	Create a key (returns the cleartext value once)
PUT	/api-keys	Update a key (the key ID is in the request body)
DELETE	/api-keys	Delete a key (the key ID is in the request body)

Rotating a key

There is no rotate/regenerate endpoint live today (a RegenerateApiKeyRequest model exists in the shared data models package, but core-api doesn’t yet implement it). Rotation is delete-and-recreate:

1. Create a new key with the same (or updated) scopes/permissions.
2. Update every system that used the old key (CI, Terraform, scripts) to the new value.
3. Once the new key is confirmed live, delete the old key.

You can also set an expiry_time up front so a key stops working automatically after a date, without needing a manual rotation.

Viewing usage & auditing

• The API Keys page shows last used at metadata.
• GET /api-keys returns the same metadata for scripting.
• Audit logs record every create/update/delete and surface requests authenticated with a key.

Revoking a compromised key

1. Delete the key immediately via Console or DELETE /api-keys.
2. Review the audit log to understand what actions were taken with it.
3. Create a replacement key with the same scope if the integration still needs access.
4. Consider rotating any other credentials the compromised system had access to.

Best practices

• Grant the narrowest permissions list and the narrowest scopes the integration actually needs — never ["*"] by default.
• Store keys in a secret manager (your CI’s secret store, a vault). Never hard-code them.
• Set an expiry_time up front, or rotate on a schedule (e.g. every 90 days) or whenever staff changes occur.
• Use a different key per automation context so you can revoke and audit independently.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify you copied the key exactly, including the dtrcs: prefix — it’s case-sensitive. Check it hasn’t expired or been deleted.
403 creating a key with a restricted permission	create_api_key, update_api_key, delete_api_key, impersonate_user, update_billing_method, and modify_licences can never be granted to an API key.
403 creating a key with a permission you lack	You can only grant permissions you already hold yourself.
403 on an action	The key lacks the required permission — recreate it with the needed permissions.
Forgotten key value	Generate a new key — plaintext values cannot be retrieved after creation.