Skip to main content

Create and manage API keys for the Humanitix public API

Create named API keys, choose what each key can do, and connect your own software to Humanitix through our public API.

Get the most advanced integration with your website or app using our Humanitix public API to fetch event, order, ticket, and tag information. You can create multiple API keys, each with a unique name and the scope of event data it will fetch.

Humanitix API documentation

The Humanitix public API documentation lists every API endpoint and explains how to make requests with your API key.

All requests require an x-api-key header with your API key.


Where to find your Humanitix API key

To find your Humanitix API keys, go to account > advanced > API keys via the top menu bar.

Only the account owner can create and manage API keys.

Your API keys are unique to your account. You cannot access API keys created by another user, even if you have shared access - and vice versa.

If another user needs access to an API key, the account owner can create an API key and share it with them securely.


How to create an API key

  1. Under scoped API keys, select create key
    ​

  2. Enter a name for the API Key
    This can describe what the API key is used for, for example, "Website sync".

  3. Choose the scopes for the API key
    A scope is a permission that controls what the API key can do. Give each API key only the scopes it needs. The available scopes are listed in the table below.
    ​

  4. Select create key and enter the OTP sent to your email or authenticator app

  5. Copy the API key straight away and store it somewhere safe.
    ⚠️ The API key is shown only once.

Your API key will appear in the list of scoped API keys, and you'll receive an email confirmation.

Lost or didn't save the API key?

Use the "..." menu > roll key action to generate a new API key


API Key scopes

The following table lists each API key scope, what it allows, and any account requirements..

Scope

What the API key can do

Events

Read lets the API key see your events

Orders

Read lets the API key see orders

Tickets

Read lets the API key see tickets

Check in tickets

Allow lets the API key check tickets in and out

Transfer tickets

Allow lets the API key move a ticket to another attendee


How to edit, rename, roll or revoke an API key

Use the "⋮" menu action next to your API key(s) to take key actions such as:

  • Edit scopes

    • Changes what the API key can do. Removing a scope takes immediate effect.

  • Rename

    • Changes the API key's name as it appears in your scoped API Key list.
      The API key and data sent are unaffected.

  • Roll key

    • Generates a new API key and keeps the same name, scopes and history. Rolling is the way to replace a lost or exposed API key.
      You can control when the existing API key stops working.

  • Revoke key

    • Stops the API key from working straight away. You can't undo revoking an API key.

Rolling an API Key

When you roll an API key, you choose when the old API key stops working:

  • Straight away

  • In 1 hour

  • In 24 hours (the default)

  • In 7 days

Update your software with the new API key before the old API key stops working. Once you've switched over, you can select Expire old key now to stop the old API key straight away.


Keeping your API keys safe

An API key gives access to sensitive data on your events, so treat every Humanitix API key like a password.

  • Don't share your API key in email, chat or support tickets.

  • Don't put your API key in code that you publish or share.

  • Every named API key starts with hx_live_, followed by 64 characters made up of the digits 0 to 9 and the letters a to f. You can add the following pattern to secret-scanning tools so they warn you if an API key is committed to code: hx_(live|test)_[0-9a-f]{64}

You'll be notified about every API key change
​
An email confirmation is sent to your account email address whenever an API key is created, rolled, revoked, renamed or has its scopes changed.
If you didn't make the change, contact our support team straight away.


Legacy API keys (Deprecated)

Accounts that created an API key before named API keys existed have a Legacy API key (deprecated) on the account > advanced > API keys page. Your legacy API key keeps working as it does today.

  • You can still show and copy your legacy API key.

  • You can generate a replacement legacy API key with New API key. Generating a replacement stops the old legacy API key working. Your named API keys aren't affected.

  • New legacy API keys can't be created. If you revoke your legacy API key, you can't get another one, so create a named API key first.

  • A legacy API key can reach events that other hosts have shared with your account. Named API keys can't. If you use your legacy API key for shared events, keep the legacy API key until you no longer need that access.


Commonly asked questions

Which events can my API key reach?

A named API key reaches only your own account's events. A named API key can't reach events that other hosts have shared with your account.

If you need an API key for another host's events, ask that host to create a named API key on their own account and share it with you securely.

Note: Legacy API (deprecated) keys work differently: a legacy API key can reach events that other users have shared with your account.

Where do I find an event ID or order ID to use with the API?

Event IDs and order IDs for the Humanitix API are found in the page URL in the Humanitix console.

Event IDs

  • An event ID is an automatically generated, unique code that identifies an event in the API when using the Get Event, Get Order(s) or Get Ticket(s) requests. Example: 5ac598ccd8fe7c0c0f212e2a

  • To find an event ID, manage the event in the console. The event ID is the code that appears after "console.humanitix.com/console/my-events/" in the page URL.

  • Event IDs can't be changed or customised.

Browser address bar in the Humanitix console showing the event ID after my-events/ in the URL

Order IDs

  • An order ID is needed when using the Get Orders request. Example: 5ac599d1a488620e6cd01d87

  • To find an order ID, open the orders report for your event and select the order. The order ID is the code in the page URL.

  • The API order ID is different to the order reference given to buyers and shown in your orders report, for example "7QVD6HEL".

  • Using an incorrect event ID or order ID returns a "500" error.

Browser address bar in the Humanitix console showing the order ID in the URL of an order page

What is the Humanitix API rate limit?

The Humanitix API rate limit is 200 requests per minute.

How do I see how an API key is being used?

Each API key on the account > advanced > API keys page shows when the API key was last used. The last used time is updated at most once an hour, so recent activity can take up to 1 hour to appear.

To see recent requests made with an API key, select View history next to the API key.

What is the Humanitix API versioning and deprecation policy?

Humanitix API updates are backwards compatible. Any change that may break an existing API call comes with 6 months' notice.

Can a user with shared access to my account create an API key?

Does Humanitix offer webhooks?

Humanitix currently does not offer native webhooks through our API; however, it is something we are looking to offer in the future. We'd recommend looking at Zapier.
Please contact our support team if you'd like to provide your use case and be notified of any updates.

Did this answer your question?