API Key Lifecycle

API keys allow external applications and scripts to access the Otesse API on behalf of your organization. Each key is scoped with specific permissions, expires on a configurable schedule, and logs every request for monitoring. This page covers the complete lifecycle of an API key from generation through rotation and revocation.

Generating an API Key

Step 1: Open the Create Modal

Navigate to Settings > Integrations > API Keys and click "Generate API Key."

Step 2: Configure the Key

Field	Description	Options
Name	Descriptive identifier (must be unique among active keys)	Free text, 1-100 characters
Description	Optional explanation of the key's purpose	Free text, 0-500 characters
Permission Scope	Broad access level	Read-Only, Read-Write, or Admin
Granular Scopes	Specific permissions within the access level	Checklist grouped by resource
Expiration	When the key stops working	30 days, 90 days, 1 year, or Never

Step 3: Review and Generate

Click "Generate API Key." The system creates a cryptographically random key in the format:

erp_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

The key consists of three parts:

• erp — Prefix identifying it as an Otesse API key
• live or test — Environment indicator
• 40 characters of base62 random data

Step 4: Copy the Key

The key is displayed exactly once in a modal with a copy-to-clipboard button. After you close this modal, the key is never shown again — the system stores only a SHA-256 hash for authentication.

If you close the modal without copying, a confirmation dialog warns: "Are you sure? This key will not be shown again."

Permission Scopes

Scope Levels

Level	Access	Use Case
Read-Only	GET endpoints only	Reporting dashboards, analytics integrations, monitoring
Read-Write	GET, POST, PUT, PATCH, DELETE on standard endpoints	Sync integrations, mobile apps, automation workflows
Admin	Full access including settings, user management, and billing	Administrative tools, superuser scripts

Granular Scopes

Within each level, you select specific resource permissions:

Scope	Description
customers.read / customers.write	List, view, create, update, delete customers
invoices.read / invoices.write	Manage invoices
payments.read / payments.write	Process and view payments
jobs.read / jobs.write	Manage jobs and work orders
products.read / products.write	Manage products and services
employees.read / employees.write	Manage employee records
reports.read	Generate and view reports
settings.read / settings.write	View and modify organization settings
webhooks.manage	Create, update, delete webhook subscriptions
integrations.manage	Manage integration connections

Scopes marked as sensitive (like settings.write and employees.write) display a warning icon and require admin role to grant.

Viewing and Managing Keys

The API Keys tab displays all keys for your organization:

Column	Description
Name	Key identifier (clickable to open detail view)
Key	Masked display: erplive...s9t0 (last 4 characters)
Scope Level	Read-Only, Read-Write, or Admin (color-coded badge)
Created	Creation timestamp
Expires	Expiration date (red if within 7 days)
Last Used	Most recent API request timestamp
Status	Active, Expired, or Revoked

Key Detail View

Click any key name to see:

• Full configuration (name, description, scope level, creation details)
• List of all granted scopes with descriptions
• Usage summary (total requests, unique IP addresses, last used)
• Recent usage log (last 50 requests with endpoint, method, status code, response time)

Key Rotation

API keys cannot have their expiration extended. To rotate a key:

1. Generate a new key with the same scopes
2. Update the external application to use the new key
3. Verify the new key works by checking usage logs
4. Revoke the old key

This ensures a clean transition with no window where both keys must be valid simultaneously — though both keys work during the transition period.

Revoking a Key

Revocation is immediate and irreversible:

1. Click "Revoke" on the key row or in the detail view
2. Confirm in the dialog: "Revoking this key will immediately disable all API access using it"
3. If the key was used in the last 24 hours, an additional warning appears
4. On confirmation, the key is immediately disabled

Revoked keys remain in the list for audit purposes but cannot be reactivated. Any API request using a revoked key receives 401 Unauthorized with the message: "This API key has been revoked."

Expiration Warnings

The system sends advance warnings before a key expires:

Timing	Notification
14 days before	In-app notification to the key creator
7 days before	In-app notification + email to organization admins
1 day before	In-app notification + email to organization admins

Limits

Limit	Value
Maximum active keys per organization	25
Key name length	1-100 characters
Description length	0-500 characters
Key format	erp{env}{40 chars base62}