API Key Authentication

Introduction

Using API Keys

API keys should be used just like any other access token. Requests should contain an Authorization header with a value starting with Bearer followed by the API key.

Managing API Keys

In order to manage API keys, the user must be authenticated using any other identity provider supported by the WebTSM Services instance that is being accessed.

Creating an API key

An API key is created by issuing a POST request to /auth/api-keys/keys

When successful (indicated by a status code 201) the response contains a string that holds the newly created API key, as well as a Location header that contains a link that can be used to view information about the key as well as for invalidation (by issuing a DELETE request).

Querying API Keys

A GET request to /auth/api-keys/keys will return information about all the keys available to the currently authenticated user. The response looks something like this:

[
    {
        "KeyId": "8bb11574-0385-43dd-92a4-ad285d9f3d30",
        "Key": {
          /* 
            Omitted for brevity.
            Contains non-sensitive information about the key material
            that is used to validate the token.
          */
        },
        "IssuedAt": "2025-04-08T11:27:25+00:00",
        "ClaimValues": {
          /*
            Omitted for brevity.
            Contains all the claims associated with the API key
          */
        }
        "OriginalIssuer": "https://login.microsoftonline.com/xxxxxxxxxxxx/v2.0",
        "KeyIssuer": "api-key://......"
    },
    //more keys 
]

To get a single key, append the KeyId to the path, i.e. make a GET request to /auth/api-keys/keys/<key-id>. A link to this endpoint is also included in the Location header returned when the key was first created.
Querying API Keys will never return the actual key that can be used for authentication, as these are never actually stored. The actual key only appears once upon creation and it is up to the user to store it securely.

Deleting/Invalidating API Keys

When an API key is no longer needed or compromised, it can be invalidated by issuing a DELETE request to /auth/api-keys/keys/<key-id> where <key-id> should be replaced with the KeyId of the key to be invalidated. If the key was successfully deleted, the response will have a status code 204 (No Content).

Using API Keys in TSM-App Via HTTP-Connection

API Keys can also be used to authenticate users for the TSM-App. For that, an HTTP-Connection needs to be established and the following entries added to the configuration file:

<HAKOMConfiguration>
  <HttpConnections>
		<HttpConnection>
			<Authentication Type="ApiKey">
				<Token>SOME_TOKEN_GOES_HERE</Token>
			</Authentication>
		</HttpConnection>
  </HttpConnections>
</HAKOMConfiguration>