# Create and manage API keys for the Humanitix 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.

[Humanitix API documentation](https://humanitix.stoplight.io/docs/humanitix-public-api)

---

# **Where to find your Humanitix API key**

To find your Humanitix API keys, go to **[account > advanced > API keys](https://console.humanitix.com/console/account/advanced/api-key)** 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. Go to **[account > advanced > API keys](https://console.humanitix.com/console/account/advanced/api-key)**

2. Under **scoped API keys**, select **create key**
​

  ![](https://downloads.intercomcdn.com/i/o/uj6ijwgj/2785621692/e60bb5e5f72c857c7800b1345424/image.png?expires=1794075300&signature=b0f5abc5a901b197dadb03634ea8579b69dcc1a50f43dcf6e88642bf2eacd06b&req=dicvE898nIdWW%2FMW1HO4zSYBJd712jv0nyjH5wjggTdjoZnl%2BfojX4qewAr%2B%0A1ScH%0A)

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

4. **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.
​

  ![](https://downloads.intercomcdn.com/i/o/uj6ijwgj/2785625775/4a2428f38ceb34c8811197a6dc05/image.png?expires=1794075300&signature=2e17d73e73741a90784a54c7aba3545ba3434a022397ef78d9520212813341d0&req=dicvE898mIZYXPMW1HO4zdaOZwwocsWo5MqI5UONIsSJSfr1ZyiT8dKlFR2n%0ANWGH%0A)

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

6. **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.

![](https://downloads.intercomcdn.com/i/o/uj6ijwgj/2785667654/38c1ab4d9b70a180bb4ffe8ad72d/image.png?expires=1794075300&signature=6d0652313954e6095d9410e310e53a93af120964ea704a196ca252c88cb1667b&req=dicvE894modaXfMW1HO4zQ3CHj9aQBkGHejJaVXUInBVKsa5WpVgcUItPc0G%0AtmtT1hCPBBc50ida93Q%3D%0A)

## **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](https://downloads.intercomcdn.com/i/o/uj6ijwgj/1464797466/414793d7de4784e2cc62ddfeaffa/image.png?expires=1794075300&signature=aa0de998c9d3db5f374654a1fc1580e3eb829b46ecc6fdf7b6e7c2a2cd2ed466&req=dSQhEs53moVZX%2FMW1HO4zZ484mL1gT24M%2F395%2BhryToryYQ%2FvqJ%2F3IRP%2FPcN%0Am9xTBPwFVwTpeZETcdc%3D%0A)

**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](https://downloads.intercomcdn.com/i/o/uj6ijwgj/2387932144/01323b8cf0b552d454cbcbaab3cb/image.png?expires=1794075300&signature=78fa2e3a5ff6320cb4bfadce77ea83c2e20d4388953eae0bb99ef8fb64c3e82e&req=diMvEcB9n4BbXfMW1HO4zcnT794HhiH5hTAOM%2BzqnhrgR1g7TT9txX2p%2Bve%2F%0AbNuK03orhlyaxLJstQY%3D%0A)

**## 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?**

No. Only the account owner can create and manage API keys, regardless of the level of shared access the other user has. If another user needs API access, the account owner can create an API key and share it with them securely. When creating an API Key or taking any key action with an API Key, a OTP sent to the account email address or linked authenticator app must be entered.