Managing API Keys

API keys provide secure, token-based authentication for external integrations (such as MaintenanceSystemIntegration) to communicate with the OT Backup API. This page explains how to create, extend, revoke, and delete API keys from the Configuration page.

flowchart LR
  A[Configuration: API Keys] --> B[Create New API Key]
  A --> C[Extend Expiration]
  A --> D[Revoke API Key]
  A --> E[Delete API Key]
  B --> F[Copy Secret Key]
  F --> G[Configure Integration]

Before you start

• You need the matching permission for the action you want to perform.
• To configure external integrations, you must have access to the physical server or deployment environment to update their appsettings.json files.

Actions you do not have access to are hidden from the API Keys table, row menus, and dialogs. If a button or menu item described here is missing, ask an administrator to grant the corresponding claim.

Create an API Key

1. Open Configuration from the navigation menu and navigate to the API Keys tab.

   

2. Select Add API Key in the top-right corner of the table.

   

3. The Create New API Key dialog opens. Fill in the required fields:

4. Select Create Key. OT Backup will generate the key and display a success dialog containing the Secret API Key.

CRITICAL WARNING: Copy the secret key immediately and store it securely. For security reasons (hash-based storage), OT Backup cannot show you this secret key again after you close the dialog. If you lose it, you must delete the key and create a new one.

Configure Integrations (Manual Setup)

Once you have copied the new secret API key, you must configure your external systems to use it.

1. Locate the configuration file (e.g., appsettings.json or appsettings.Production.json) for your integration service (MaintenanceSystemIntegration).
2. Open the file in a text editor.
3. Locate or add the ApiKeyAuthenticationOptions section and paste your copied secret key:

{
  "AppSettings": {
    "ApiKey": "<PASTE_YOUR_SECRET_KEY_HERE>"
  }
}

4. Save the file and restart the integration service. The service will now securely authenticate with OT Backup.

Extend API Key Expiration

API Keys might expire based on system policies. You can extend an active key's lifespan without needing to generate a new secret key.

1. On the API Keys tab, open the row's More options menu (the ⋮ icon) or click the Extend button for the respective key.

2. The Extend API Key dialog opens.

   

3. Choose a new date from the calendar.

4. Select Save Changes.

Maximum Expiration Policies

Depending on your system's security configuration (AppSettings:ApiKeyMaxExpiration), OT Backup may enforce a maximum lifespan for API keys (e.g., 1 year, 6 months, 30 days).

If a limit is configured, the calendar will prevent you from selecting dates beyond the allowed maximum, and you will see a warning indicating the maximum allowed date.

The option to make a key "Permanent" will be hidden if strict expiration policies are active.

Revoke an API Key

If you suspect an API key has been compromised, but you want to keep its historical record for audit purposes, you should Revoke it.

1. On the API Keys tab, open the row's More options menu and choose Revoke.

   

2. Confirm the prompt:

   Are you sure you want to revoke the API key ''? This action cannot be undone and any integration using this key will immediately lose access.

3. Choose Revoke. The key's status will change to Revoked and all authentication attempts using this key will immediately return a 401 Unauthorized error.

Note: A revoked key cannot be reactivated. You must create a new key to restore integration access.

Delete an API Key

Deleting an API key removes it entirely from the OT Backup database. Use this for keys created by mistake or old revoked keys that are no longer needed for auditing.

1. On the API Keys tab, open the row's More options menu and choose Delete.

   

2. Confirm the prompt:

   Are you sure you want to delete the API key ''?

OT Backup shows API Key deleted and removes the row from the table.

Troubleshooting

See Also

• Creating a Backup
• Restoring a Backup
• Adapters