Managing API Users and Authentication (API Keys and Auth Tokens)

This guide will walk you through creating and managing API users within the TNZ Dashboard. You'll learn how to handle authentication using both legacy API Keys and modern JWT Authorization Tokens.

For robust security and granular control, we strongly recommend creating a unique API user for each of your applications or integrations. This practice, known as the principle of least privilege, offers several advantages:

• Usage Tracking: Easily monitor the API usage of each individual application.

• Access Revocation: If an application is compromised or retired, you can revoke its specific credentials without affecting your other active integrations.

• Simplified Troubleshooting: Isolate issues to a specific application's API user, making debugging more efficient.

You can create multiple API users to separate applications. If you need to automate the user creation process, TNZ provides a user creation API. Please contact our support team for access and documentation.

API Keys vs. Auth Tokens: Understanding the Difference

TNZ's APIs use two methods for authentication, depending on the version of the API you are using.

• API Keys (Legacy): Our older APIs use a Sender and APIKey pair. These credentials are typically passed within the Body of the API request.

• Authorization Tokens (Current): Newer versions of our APIs utilize a JSON Web Token (JWT) Authorization Token. This token is more secure and is passed in the HTTP Header of the API call. We recommend using token-based authentication for all new development projects.

How to Create or Edit an API User

1. Log in to the TNZ Dashboard.

2. Navigate to the Users menu from the main navigation.

3. Click the Create button or click on an existing user's name to modify their settings.

4. Select the API tab within the user's profile.

Here, you can enable or disable API access for the user and configure their permissions.

How to Find Your Auth Token or API Key

Once API access is enabled for a user, their authentication credentials can be accessed from the API tab.

1. From the Users menu, select the user you wish to manage.

2. Go to the API tab.

3. You will see the Auth Token and, if applicable, the legacy APIKey.

4. Click the Copy button next to the credential you need. This will copy it to your clipboard, preventing transcription errors.

(Image: A screenshot of the API Options tab in the TNZ Dashboard, highlighting the "Copy" buttons for the Auth Token and APIKey.)

Using Your Auth Token in an API Request

When integrating with our modern APIs, the Authorization Token should be placed in the HTTP Header of your request, prefixed with "Basic ".

Example:

Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...   <- Your Auth Token

Replace the example token with the full Auth Token you copied from the Dashboard.

Using Your APIKey in an API Request

When integrating with our legacy APIs, the APIKey should be placed in the body of your request, along with the Senders name.

Example:

Sender=example@domain.com   <- Your Sender's Username

Token=hafje98u210d1i        <- Your APIKey

Replace the Sender and Token with the values copied from the Dashboard.

How to Revoke an Auth Token or API Key

For security purposes, you can instantly revoke an existing credential and generate a new one. This is a critical step if you believe a key has been exposed or when decommissioning an application.

1. Navigate to the user's API tab in the Dashboard.

2. Click the Recycle button next to the Auth Token or APIKey.

Warning: When you recycle a credential, the old one is immediately and permanently revoked. Any application or script still using the old Auth Token or APIKey will fail to authenticate and will no longer be able to access the API. You must update your applications with the newly generated credential to restore functionality.