> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> API keys allow external applications and services to securely authenticate HTTP requests to GermainUX without using a username and password.

Service
`Authentication`

Availability
2026.1 or later

> **[Use an API Key](#use-an-api-key)**
>
> Bearer token request example

> **[Manage API Keys](#manage-api-keys)**
>
> Disable, delete and review keys

> **[Troubleshooting](#troubleshooting)**
>
> Fix 401 authentication errors

> **[Security Recommendations](#security-recommendations)**
>
> Key hygiene best practices

## Overview

API keys allow external applications and services to securely authenticate HTTP requests to GermainUX without using a username and password.

API keys use the Bearer authentication scheme and can be assigned only the permissions required by the integration.

## Before You Begin

To create, enable, disable, or delete API keys, your account must have the **Manage Users** permission.

API-key authentication must also be enabled globally in the GermainUX configuration.

## Create an API Key

**1. Go to Germain Workspace > Left Menu > System > Auth Settings > API Keys**

**2. Click Create API Key**

**3. Configure the API key using the fields below**

**4. Click Finish**

**5. Copy the generated API key and store it securely**

> [!NOTE]
>
> **Important:** The API key is displayed only once. You cannot retrieve it after closing the dialog. If the key is lost, create a replacement and delete the old key.

The API key’s name, expiration date, and permissions cannot be changed after creation.

## API Key Settings

| Field | Description |
| - | - |
| **Name** | A descriptive name that identifies the application, service, or purpose of the API key. |
| **Expires** | Date on which the key becomes invalid. If no date is specified, the key does not expire. Setting an expiration date and rotating keys periodically is recommended. |
| **Privileges** | Operations that requests authenticated with the key can perform. For example, select **View Data** if the integration needs to query data from the GermainUX Datamart. |

Grant only the privileges required by the application or service using the key.

## Use an API Key

Include the API key in the HTTP `Authorization` header using the Bearer authentication scheme:

```text theme={null}
Authorization: Bearer <api-key>
```

The following JavaScript example queries GermainUX data using an API key:

```text theme={null}
fetch("https://<germainux-host>/query/query", {
  method: "POST",
  headers: {
    "Accept": "*/*",
    "Content-Type": "application/json",
    "Authorization": "Bearer <api-key>"
  },
  body: JSON.stringify({
    factType: "InternalEvent",
    measures: [
      "time.day",
      "time.month",
      "time.year",
      "avg(value)",
      "count(id)"
    ],
    orders: [
      "time.day asc",
      "time.month asc",
      "time.year asc"
    ],
    pivots: [
      "time.day",
      "time.month",
      "time.year"
    ],
    timeRange: [
      "2026-01-01T00:00:00+01:00",
      "2026-01-02T00:00:00+01:00"
    ],
    timeMode: "INTERSECTS",
    timeOffset: "+01:00",
    filter: "type == 'GermainAPM:Service CPU Usage'",
    ignoreCache: false
  })
});
```

Replace `<germainux-host>` with the hostname of your GermainUX environment and `<api-key>` with the generated key.

Do not embed API keys in publicly accessible browser code. Store them in a secure secret-management system and use them only from trusted applications or services.

## Manage API Keys

Go to:

**Germain Workspace > Left Menu > System > Auth Settings > API Keys**

From this page, administrators with the **Manage Users** permission can:

* Create API keys
* Enable or disable API keys
* Delete API keys
* Review key names, expiration dates, privileges, and status

API key settings cannot be edited after creation. To change a key’s name, expiration date, or privileges:

**1. Create a replacement key with the required settings**

**2. Update the application or service to use the new key**

**3. Confirm that requests succeed**

**4. Disable or delete the previous key**

Disabling or deleting a key takes effect immediately. Requests using that key will fail with an HTTP `401 Unauthorized` response.

## Enable or Disable API-Key Authentication Globally

API-key authentication can be enabled or disabled for the entire GermainUX environment.

1. Open the GermainUX Config Console.
2. Navigate to:

```text theme={null}
germain.apm.services.authentication
```

1. Enable or disable:

```text theme={null}
bearerAuthenticationEnabled
```

1. Restart all Tomcat instances to apply the change.

When API-key authentication is disabled:

* Existing API keys are ignored.
* Requests authenticated with API keys fail.
* The **API Keys** menu item is no longer available in the Germain Workspace.

## Rotate an API Key

To rotate a key without interrupting the integration:

**1. Create a new key with the required privileges and expiration date**

**2. Store the new key securely**

**3. Update the external application or service**

**4. Test an authenticated request**

**5. Disable the old key**

**6. Confirm that the integration continues to operate**

**7. Delete the old key when it is no longer required**

## Troubleshooting

If an API request fails, verify that:

* API-key authentication is globally enabled.
* All Tomcat instances were restarted after changing the global setting.
* The `Authorization` header uses the `Bearer` scheme.
* The complete API key was copied without additional spaces or characters.
* The key is enabled and has not expired.
* The key has the privileges required by the requested operation.
* The request URL and HTTP method are correct.
* The key has not been disabled, deleted, or replaced.

An HTTP `401 Unauthorized` response generally indicates that the key is missing, invalid, expired, disabled, or that API-key authentication is globally disabled.

An HTTP `403 Forbidden` response generally indicates that the key is valid but does not have sufficient privileges for the requested operation.

## Security Recommendations

* Assign only the minimum required privileges.
* Set an expiration date for every key.
* Use a separate key for each application, service, or environment.
* Store keys in an approved secret-management system.
* Never commit keys to source control.
* Never include keys in client-side code, screenshots, logs, support tickets, or documentation.

> **Show all 10**
>
> * Transmit API requests only over HTTPS.
> * Rotate keys periodically and immediately after suspected exposure.
> * Disable or delete keys that are no longer required.
> * Review active keys and their privileges regularly.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.