Skip to main content

​
Overview

API keys provide programmatic access to CaseBender. Open Settings → Account → API Keys to manage keys available to your account and current organization. The page provides:
  • Search and status or tier filters
  • Masked key identifiers
  • Status, tier, last-used time, and request count
  • Usage statistics
  • Lifecycle actions such as rotation, suspension, revocation, and deletion
An API key is a credential. Store it in an approved secrets manager, never commit it to source control, and never include it in logs, screenshots, tickets, or chat messages.

​
Prerequisites

  • Your role must allow write operations and API-key management.
  • Available scopes are filtered according to your role.
  • Creating, revoking, or deleting a key can require step-up authentication.
  • Your organization can impose additional authentication and access policies.
Read-only roles can view permitted information but cannot mutate keys.

​
Create an API key

1

Open API Keys

Go to Settings → Account → API Keys.
2

Start creation

Select Create API Key.
3

Describe the key

Enter a clear Name and optional description identifying the workload, owner, and purpose.
4

Select a tier

Choose the tier appropriate for the workload’s expected request volume. Available tiers range from Basic through Unlimited.
5

Set an expiration

Optionally enter the number of days until expiration. Prefer short, policy-aligned lifetimes for production credentials.
6

Select scopes

Choose at least one scope. Use Select all only when the workload legitimately requires every scope available to your role.
7

Create and authenticate

Select Create Key and complete step-up authentication when prompted.
8

Save the credential

Copy the complete key from Save Your API Key into an approved secrets manager before selecting Done.
The complete key is displayed only once. CaseBender stores only the information required to validate and identify it; the plaintext credential cannot be retrieved later.

​
Choose scopes

Scopes use a resource-and-action pattern, such as cases:read or organizations:*. Scope categories can include cases, alerts, tasks, users, teams, organizations, settings, and API-key management. Follow least privilege:
  • Use read-only scopes for reporting and search workloads.
  • Grant write scopes only when the integration performs mutations.
  • Avoid wildcard and administrative scopes for single-purpose integrations.
  • Create separate keys for unrelated services or environments.
  • Review scope requirements whenever an integration changes.
The Settings creation form only offers scopes allowed by your current role. API requests are evaluated against the key’s scopes and other enforced data controls.
Grant api-keys:write, wildcard, or administrative scopes only to trusted automation that is explicitly authorized to create or manage other credentials.

​
Choose a tier

The tier records the intended service class for a key. The available tiers are:
  • Basic
  • Standard
  • Professional
  • Enterprise
  • Unlimited
Effective request, bulk-operation, and concurrency limits depend on deployment configuration. Validate production throughput and enforcement with your platform administrator rather than assuming that selecting a tier changes the active limits or makes a key unrestricted.

​
Authenticate API requests

Use the complete key with one of the supported single-key headers.

​
Recommended: Bearer token

​
Alternative: X-Api-Key

Store the key in an environment variable or secret injection mechanism. Do not paste a real key directly into shell history or source code.
See the API Reference introduction for additional examples.

​
Understand key statuses

  • Active keys can authenticate requests, subject to scope and policy checks.
  • Suspended keys are temporarily disabled and can be reactivated.
  • Revoked keys are permanently invalid.
  • Expired keys have passed their configured expiration.

​
View usage statistics

Open a key’s action menu and select View Stats to review:
  • Total requests
  • Successful requests
  • Failed requests
  • Average response time
  • Top endpoints
Use these statistics to identify unused credentials, unexpected endpoints, and workloads that require a different tier.

​
Rotate a key

Rotation replaces the current secret with a new one.
1

Prepare the consumer

Confirm that you can update the consuming service immediately and have a rollback plan.
2

Rotate

Open the key’s action menu and select Rotate Key.
3

Save the new key

Copy the newly displayed credential into your secrets manager.
4

Update and verify

Update the consuming workload, restart or redeploy it as required, and make a scoped test request.
Rotation invalidates the previous secret. Coordinate the change to avoid an integration outage.
Rotation is operator-initiated. A stored rotation interval does not by itself guarantee that CaseBender will rotate and distribute a replacement key automatically.

​
Suspend or reactivate a key

Use Suspend to stop a key temporarily during an investigation or planned maintenance. Use Reactivate only after confirming that the credential and its consumer are trusted. Suspension is preferable to deletion when you need a reversible containment action.

​
Revoke a key

Use Revoke when a credential is compromised, no longer trusted, or permanently retired. Revocation can require step-up authentication and cannot be reversed. After revocation:
  1. Remove the secret from all consumers.
  2. Review usage statistics and security telemetry.
  3. Investigate unexpected requests.
  4. Create a separate replacement key only if the workload remains authorized.

​
Delete a key

Deletion removes the key record and its direct management visibility. It can require step-up authentication.
Revoke a key before deleting it when you need a clear credential-retirement sequence. The current action menu does not provide a separate confirmation dialog for every destructive operation.

​
Security recommendations

  • Assign a named human owner and workload owner.
  • Use separate keys for production, staging, and development.
  • Set an expiration aligned with your credential policy.
  • Rotate immediately after suspected exposure.
  • Monitor failed requests and unexpected endpoints.
  • Revoke unused keys instead of leaving them active.
  • Never send keys through email or collaboration tools.

​
Troubleshooting

​
Create Key is rejected

Enter a name, select at least one scope, confirm that your role has write access, and complete any step-up authentication challenge.

​
An API request returns 401

Confirm that the complete active key is supplied as a Bearer token or X-Api-Key, and verify that it has not expired, been suspended, or been revoked.

​
An API request returns 403

The key authenticated successfully but lacks the required scope or data access. Add only the minimum required scope through an authorized key-management workflow.

​
Requests are rate limited

Reduce request frequency, honor retry guidance from the response, or ask an administrator whether the workload requires another tier.

​
The complete key is no longer visible

Plaintext keys cannot be retrieved. Rotate the key or create a replacement and update the consumer.

​
API reference

​
Related guides