> For the complete documentation index, see [llms.txt](https://docs.ixhello.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ixhello.com/ixhc2/api-key-management.md). # API Key Management ### Overview API Key Management provides a secure, self-service way for iX Hello organizations to create, manage, rotate, and revoke API keys directly from the Admin Dashboard. This eliminates the need for manually provisioned static keys and gives organizations complete control over API access. With API Key Management, organizations can create multiple API keys, assign permissions, track usage, enforce expiration policies, and immediately revoke compromised keys when needed. *** ### Why API Key Management? Previously, API access relied on a single static API key shared across the organization. This approach made key management difficult and introduced security risks. #### Before vs. After | Before | After | | ------------------------------------------- | ----------------------------------------------------- | | Single static bearer token per organization | Multiple named API keys per organization | | Keys manually provisioned and shared | Self-service key creation and management | | Key stored as retrievable secret | Keys hashed and secured at rest | | No expiration or rotation support | Configurable expiration and key rotation | | No revocation mechanism | Immediate key deactivation and revocation | | No access restrictions | Scope-based access control | | No usage visibility | Usage metrics, last-used timestamps, and audit trails | *** ## Key Types API Key Management supports two types of API keys. ### Personal Access Keys Personal Access Keys are intended for individual users. #### Characteristics * Owned by the user who creates them. * Visible only to the key owner. * Cannot be viewed, edited, or used by other users. * Limited to 2 keys per user. * Suitable for: * Development work * Testing * Personal automation * Individual integrations #### Security Isolation Personal keys are protected through server-side cross-user isolation. If another user attempts to: * View the key * Modify the key * Use the key via backend APIs the request is rejected with a 403 Forbidden response. *** ### Service Keys Service Keys are designed for shared integrations and production use cases. #### Characteristics * Can only be created by Organization Administrators. * Visible to all Organization Administrators. * Intended for customer integrations and shared automation. * No limit on the number of service keys. * Suitable for: * Customer-facing integrations * Production workloads * Shared automation * Headless API integrations *** ## Security Model API Key Management follows security best practices to protect API credentials. ### Hashed Storage API keys are never stored in plain text. The platform stores: * A salted hash of the key * A non-secret key prefix * The last four characters Because only the hash is stored, a database leak cannot expose usable API keys. *** ### One-Time Display When a key is created: * The full key is displayed only once. * Users must copy the key immediately. * The raw key cannot be viewed again after the dialog is closed. **Important:** If you lose the key, it cannot be recovered. You must rotate or create a new key. *** ### Immediate Revocation Keys can be deactivated at any time. When a key is revoked: * Revocation takes effect immediately. * Cached key validations are invalidated. * New API requests using the revoked key are rejected instantly. *** ### Automatic Expiration Cleanup Expired keys are automatically removed by a scheduled background job. Benefits include: * Reduced security risk * No manual cleanup required * Automatic removal of unused credentials *** ## Key Scopes Service keys can be restricted using scopes. Scopes help enforce the principle of least privilege by limiting what a key can access. #### Supported Scope Types **Flow Scopes** Restrict access to specific flows that can be executed via Headless APIs. **Channel Scopes** Restrict access to specific communication channels such as: * Chat * Voice * Other supported connectors **Operation Scopes** Restrict permitted actions such as: * Read-only access * Execute access * Other operation-specific permissions If a key is compromised, its impact is limited to the configured scopes. *** ## Accessing API Key Management Navigate to: **Flows→ Integrations → API Keys** #### Access Requirements The API Keys page is available only to users with the appropriate API key management entitlement. If you do not see the page, contact your Organization Administrator.
*** ## Creating an API Key ### For Organization Administrators Admins can create: * Personal Access Keys * Service Keys
### For Non-Admin Users Non-admin users can create only: * Personal Access Keys *** ### Steps to Create a Key 1. Navigate to **Settings → Integrations → API Keys**. 2. Click **Generate New Key**.
1. Choose the key type: * Personal Access Key * Service Key (Admins only)
1. Enter a unique key name. 2. Select an expiration period: * 7 days * 30 days * 60 days * 90 days * Custom expiration date * Never
1. If creating a Service Key, configure the required scopes. 2. Click **Create**. 3. Copy the generated API key from the one-time display dialog. **Important:** Store the key in a secure location such as a password manager or secrets vault. The key cannot be retrieved after the dialog is closed.
*** ## Monitoring API Keys The API Keys page displays all relevant information for each key. | Field | Description | | --------------- | --------------------------- | | Name | User-defined key name | | Prefix / Last 4 | Partial key identifier | | Type | Personal or Service | | Scopes | Assigned permissions | | Created Date | Key creation date | | Expiration | Expiration date or Never | | Last Used | Most recent usage timestamp | | Status | Active or Revoked | This information helps administrators monitor active integrations and identify unused or expiring keys. *** ## Rotating an API Key Key rotation allows credentials to be updated without disrupting integrations. ### Steps 1. Locate the key. 2. Select **Rotate**. 3. A new API key is generated. 4. Optionally configure a grace period during which both keys remain valid. 5. Update connected applications to use the new key. 6. After the grace period ends, the old key is automatically revoked. #### Benefits * Improves security * Minimizes downtime * Supports credential renewal best practices *** ## Deactivating a Key If a key is believed to be compromised or temporarily no longer required, it can be deactivated. ### Steps 1. Locate the key. 2. Click **Deactivate**. 3. The key becomes inactive immediately. #### Reactivation A deactivated key can be reactivated if required.
*** ## Deleting a Key Deleting a key permanently removes it from the system. ### Steps 1. Locate the key. 2. Click **Delete**. 3. Confirm the deletion. **Warning:** Deleted keys cannot be recovered.
*** ## Using API Keys with Headless APIs ### Authentication Include the API key as a Bearer token in the HTTP Authorization header. Authorization: Bearer \ #### Example cURL Request ``` curl --request POST \ --url https:///api/headless/session \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" ```
## How API Key Verification Works When a Headless API request is received: 1. The Channel Gateway extracts the Bearer token. 2. The API key is validated against the key store. 3. Cached validation data is checked. 4. The platform verifies: * The key exists * The key is active * The key has not expired * The key has the required scopes 5. If validation succeeds, the request is authorized. 6. If validation fails, an appropriate error is returned. #### Common Errors | Error | Reason | | ----------------------------- | ------------------------------ | | 401 Unauthorized | Key missing | | 401 Unauthorized: Key Expired | Key is no longer valid | | 403 Forbidden | Key lacks required permissions | | 403 Forbidden | Cross-user access attempted | *** ## Unified Authentication Model API keys are now part of a unified platform authentication strategy. | Authentication Method | Use Case | Managed By | | -------------------------------- | ----------------------------------------- | ------------------------------------- | | API Keys | Customer integrations and Headless APIs | Admin Dashboard | | Widget JWT | Embedded website chat widgets | Existing widget authentication system | | OAuth2 Client Credentials / mTLS | Internal service-to-service communication | Existing platform infrastructure | Existing Widget JWT and OAuth2 authentication mechanisms remain unchanged. *** ## Monitoring, Audit, and Governance ### Audit Events The platform generates audit events for all key lifecycle operations. | Event | Description | | -------------------- | ------------------------------------------ | | api\_key.created | New key created | | api\_key.rotated | Key rotated | | api\_key.revoked | Key revoked | | api\_key.reactivated | Key reactivated | | api\_key.deleted | Key permanently deleted | | api\_key.expired | Key automatically removed after expiration | *** ### Usage Telemetry The platform tracks key activity to support governance and operational monitoring. #### Available Metrics * Last-used timestamp * Per-key usage metrics * Audit history * Optional rate-limit tracking * Optional quota tracking These metrics help organizations identify unused keys, monitor API consumption, and improve security. *** ### Summary API Key Management introduces a secure and scalable way to manage API authentication across iX Hello. With support for Personal Access Keys, Service Keys, scoped permissions, expiration policies, audit trails, and immediate revocation, organizations can securely manage integrations while maintaining full visibility and control over API access. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ixhello.com/ixhc2/api-key-management.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.