API key management

Overview

API keys provide programmatic access to Enterprise h2oGPTe through the REST API and Python SDK. Each API key belongs to a specific user and can target a single collection or provide global access.

Enterprise h2oGPTe provides API key lifecycle management, including:

• Key types: Global, collection-scoped, and admin-created user-specific keys
• Expiration policies: Time-based expiration and inactivity-based automatic expiration
• Permission controls: Role-based permissions that govern who can create keys and what scope they can use
• Automatic deactivation: Automatic expiration of keys when an administrator revokes the permissions that authorized their creation

To manage API keys through the System Dashboard UI, see Application API Keys.

note

The system stores API keys as SHA-256 hashes and never stores the plaintext key in the database, retaining only the last four characters for identification.

Key types

Enterprise h2oGPTe supports three API key types:

Type	Scope	Description
Global	Full API access	Unrestricted access to all resources available to the key owner.
Collection-scoped	Single collection	Access restricted to a single collection. Use this type to limit the impact of a compromised key.
User-specific (admin)	Full API access	Created by an administrator on behalf of another user. The key operates with the target user's permissions.

Access the API keys section

1. In Enterprise h2oGPTe, click account_circle Account Circle.
2. Select System Dashboard.
3. In the Configuration section, click System settings.
4. Scroll to the API Keys section to view active keys.

note

All API key management actions on the System Settings page require administrator privileges.

Expiration policies

Time-based expiration

Administrators can configure a global maximum lifetime for API keys using the global_api_key_expiry_days setting. When this setting is active:

• The system rejects any requested expiration that exceeds the global limit.
• Keys created without a specified expiration automatically receive the global limit.
• Changes to the global limit apply to newly created keys. To update existing keys, use the expiration update API.

Configure the global API key expiration to match your organization's security policy. Use a value between 90 and 365 days for production deployments:

curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/global_api_key_expiry_days" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "365"}'

Inactivity-based expiration

In addition to time-based expiration, administrators can set an inactivity interval on individual API keys. The system automatically expires keys that are not used within the configured period.

The system tracks usage with a last_used_at timestamp and total_calls counter on each API key.

# Set inactivity interval (in days) on an API key
curl -X PATCH "https://<YOUR_DOMAIN>/api/v1/admin/api_keys/inactivity_interval/{key_id}" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"inactivity_interval": 30}'

API key permissions

Two role-based permissions control API key creation:

Permission	Identifier	Description
Create collection-scoped keys	h2ogpte/api_key/create	Lets users create API keys scoped to a specific collection.
Create global keys	h2ogpte/api_key/create_global	Lets users create unrestricted API keys. Requires api_key/create as a prerequisite.

The admin, default, and user roles have both permissions by default. For least-privilege configurations, administrators can:

• Remove api_key/create_global from roles that don't need unrestricted API access, restricting them to collection-scoped keys only.
• Remove api_key/create entirely from roles that shouldn't create any API keys.

# Remove global key creation from a role
curl -X DELETE "https://<YOUR_DOMAIN>/api/v1/roles/{role_id}/permissions/h2ogpte/api_key/create_global" \
  -H "Authorization: Bearer <API_KEY>"

Automatic deactivation on permission changes

When a role loses the api_key/create or api_key/create_global permission, the system automatically expires all active API keys for affected users. This prevents API keys from outliving the permissions that authorized their creation.

The following table describes how each revocation affects active keys:

Permission revoked	Effect on active keys
api_key/create	The system expires all active keys for affected users.
api_key/create_global	The system expires only global (non-collection-scoped) keys.

The system checks all of a user's roles (both direct and group-based) and only expires keys when none of the remaining roles grant the revoked permission. This prevents false deactivation when a user holds the permission through multiple roles.

Example: A user has roles analyst and developer, both with api_key/create_global. Revoking the permission from analyst has no effect because developer still grants it. Revoking it from developer as well triggers automatic expiration of the user's global keys.

Manage API keys with the REST API

Create a global API key for a user

Create an API key for a specific user with a defined expiration period:

curl -X POST "https://<YOUR_DOMAIN>/api/v1/admin/api_keys" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<USER_ID>", "name": "production-service-key", "expires_in": "90 days"}'

List all API keys

Retrieve all API keys with pagination:

curl -s "https://<YOUR_DOMAIN>/api/v1/admin/api_keys?offset=0&limit=100" \
  -H "Authorization: Bearer <API_KEY>"

Deactivate an API key

Deactivation sets the expiration to the current time, making the key immediately invalid. You can't reverse this action.

curl -X POST "https://<YOUR_DOMAIN>/api/v1/admin/api_keys/deactivate/{key_id}" \
  -H "Authorization: Bearer <API_KEY>"

Update API key expiration

Set a new expiration period on an existing API key:

curl -X PATCH "https://<YOUR_DOMAIN>/api/v1/admin/api_keys/expire/{key_id}" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": "60 days"}'

Delete an API key

This permanently removes the API key record.

curl -X DELETE "https://<YOUR_DOMAIN>/api/v1/admin/api_keys/{key_id}" \
  -H "Authorization: Bearer <API_KEY>"

Manage API keys with the Python SDK

The following example demonstrates common API key management operations using the Python SDK:

from h2ogpte import H2OGPTE

admin = H2OGPTE(address="https://<YOUR_DOMAIN>", api_key="<API_KEY>")

# Create a global API key for a user (returns the secret key, shown only once)
secret_key = admin.create_api_key_for_user(
    user_id="<USER_ID>",
    name="production-service-key",
    collection_id=None,
    expires_in="90 days"
)

# Create a collection-scoped key
collection_key = admin.create_api_key_for_user(
    user_id="<USER_ID>",
    name="analytics-collection-key",
    collection_id="<COLLECTION_ID>",
    expires_in="30 days"
)

# List all API keys
keys = admin.list_all_api_keys(offset=0, limit=100, key_filter="")
for api_key in keys:
    print(f"ID: {api_key.id}, Name: {api_key.name}, Hint: ...{api_key.hint}, "
          f"Expires: {api_key.expires_at}, User: {api_key.username}")

# Deactivate a compromised key
admin.deactivate_api_key(api_key_id="<KEY_ID>")

# Update expiration
admin.set_api_key_expiration(api_key_id="<KEY_ID>", expires_in="60 days")

Best practices

Follow these practices to maintain a secure API key environment:

Practice	Recommendation
Expiration policy	Configure global_api_key_expiry_days to a value between 90 and 365 days.
Inactivity interval	Set 30 days for service keys, 14 days for interactive user keys.
Key naming	Include the purpose, environment, and creation date in the key name (for example, prod-analytics-2026-04).
Rotation	Rotate service keys on a regular cadence matching your expiration policy.
Scope restriction	Use collection-scoped keys whenever full API access is not required.
Creation permissions	Remove api_key/create_global from roles that don't need unrestricted keys.
Audit	Periodically list all keys, review total_calls and last_used_at, and deactivate unused keys.
Emergency revocation	Deactivate compromised keys immediately using the admin API.

Related topics

• System Settings - Configure global API key expiration and other system settings
• Roles and Permissions - Manage API key creation permissions per role
• APIs - Use API keys for programmatic access to Enterprise h2oGPTe

---

Feedback

• Submit and view feedback for this page
• Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai