Skip to main content
API and MCP

Creating an API key and managing permissions

An API key is a secret credential used by an external system to authenticate its access to "Hanna". Use a separate, clearly named key for each integration and grant only the necessary permissions.

Last updated 13 days ago

What you’ll do

An API key is a secret credential used by an external system to authenticate its access to Hanna. Use a separate, clearly named key for each integration and grant only the necessary permissions.

Before you begin

You need administrator access or API and MCP access granted by an administrator. Grant only the permissions required for the specific integration and do not use personal keys for shared company integrations.

How to create a key

  1. Open System Settings → API and MCP.
  2. Click New record.
  3. Enter a name that will allow you to identify the integration later.
  4. Select Personal or System.
  5. Select the required permissions.
  6. Click Save.
  7. Immediately copy the displayed key to a secure secret storage.

The full key is displayed only once. You will not be able to view it again after closing the window.

What the general permissions mean

  • Read allows retrieving and searching for data. This permission is mandatory. - Write allows creating and editing records.
  • Delete allows deleting records specified in the API documentation.

If the integration only reads data, do not grant write and delete permissions.

Personal key

A personal key operates on behalf of the user who created it. The integration can only view and modify what is permitted by the user's role, individual user settings, and field-level settings.

This type is convenient for a personal tool or process that needs to run on behalf of a specific user. If the user is disabled or their settings are changed, the integration's capabilities may also change.

System key

A system key is intended for a general company integration whose operation should not depend on a single user account. It is created by an administrator.

Selecting a system key displays a module matrix. For each module, you can individually grant permission to:

  • view;
  • create;
  • edit;
  • delete.

Not all modules support all actions. Select only the rows required for the specific integration.

How to use the key

The API key is passed in the header:

Authorization: Bearer {jūsų-raktas}

Do not include the key in the URL, a public code repository, comments, or a user manual. If the key might have been exposed, generate a replacement and revoke the old one.

Replacing and revoking the key

Key actions are available in the API and MCP list.

Selecting Replace creates a replacement key. The old key remains active, allowing you to update the integration and test the new key first. Once the new key is working, revoke the old one.

Selecting Revoke immediately deactivates the key. Check which system is using it before doing so.

The list also displays the expiration date and last usage time. This helps identify keys that are no longer in use or have not been replaced on time.

If the key is not working

  • 401 usually indicates an incorrect, expired, or revoked key.
  • 403 means the key is recognized, but the necessary general or module permissions are missing.
  • 422 indicates invalid or missing data. - 429 indicates that too many Tickets requests were sent within a short period.

Check the specific fields and operations via the API Documentation link at the top of the page.

If the request still fails after you check the documentation and permissions, send Hanna Customer Support your company's Hanna address, HTTP method, API path, response status code, attempt time and time zone, and a sanitized response body. Do not send the API key or Authorization header.

Was this helpful?

Still need help? Ask the team