Get the most advanced integration with your website using our Humanitix public API to fetch event, order, ticket, and tag information.
Use this article to create, manage and secure the API keys that connect your own software, or a service you use, to your Humanitix account through the Humanitix public API. You can create as many named API keys as you need, give each API key a name, and choose exactly what each API key can do.
Who can manage API keys: this article is for event hosts. Only the account owner can create and manage API keys. Collaborators on your account can't see or manage API keys, whatever their access level. If a collaborator needs API access, the account owner can create an API key and share it with them securely.
Where do I find my API keys?
Your Humanitix API keys are in the Humanitix console. Go to account > advanced > API keys via the top menu bar.
If you can't see your API keys, check that you're signed in as the account owner. Collaborators can't see or manage API keys.
How do I create an API key?
Creating a named API key takes a few steps, and you'll confirm the new API key with your second factor (for example, a code we email you).
Go to account > advanced > API keys.
In the Scoped API keys section, select Create key.
Enter a name that says what the API key is for, for example "Website sync".
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.
Select Create key, then confirm with your second factor, such as an emailed code.
Copy the API key straight away and store it somewhere safe. The API key is shown only once.
Once the API key is created, it appears in your list of API keys and we send you an email confirming the API key was created. If you lose the API key before saving it, roll the API key to get a new one (see "How do I change, rename, roll or revoke an API key?" below).
What can each API key scope do?
The following table lists each API key scope, what the scope allows, and any account requirements for the scope.
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 do I keep my 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}
We email you about every API key change. We send an email 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.
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.
Legacy API keys work differently: a legacy API key can reach events that other hosts have shared with your account. See "What happens to my legacy API key?" below.
How do I change, rename, roll or revoke an API key?
You can change an existing API key from the ⋮ menu next to the API key on the account > advanced > API keys page. The following options are available:
Edit scopes changes what the API key can do. Anything that needs a scope you remove stops working straight away.
Rename changes the API key's name. The API key itself doesn't change, so your software keeps working.
Roll key gives you a new API key and keeps the same name, scopes and history. Rolling is the way to replace a lost or exposed API key.
Revoke key stops the API key working straight away. You can't undo revoking an API key.
When does my old API key stop working after I roll it?
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.
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 happens to my legacy API key?
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.
Where is the 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.
Commonly asked questions
Where do I find an event ID or order ID to use with the API?
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.
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.
What is the Humanitix API rate limit?
What is the Humanitix API rate limit?
The Humanitix API rate limit is 200 requests per minute.
What is the Humanitix API versioning and deprecation policy?
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 collaborator on my account create an API key?
Can a collaborator on my account create an API key?
No. Only the account owner can create and manage API keys, whatever access level a collaborator has. If a collaborator needs API access, the account owner can create an API key and share it with them securely.