Creating an API key

An API is a door at the back of your account. Where you click in your management screen, another program can use that door to fetch your data directly: your products, your prices, your free places, your sales.

That is useful when you want to, for example:

• show on your own website which guided tours still have room this week;
• let your accountant pull in your turnover figures automatically;
• connect your member list to another program.

Whoever builds that integration — your web developer, your bookkeeping package, a friend who can program — needs two things from you: the address and a key. You will find both on a single screen.

Good to know: the API is part of a larger plan. On a smaller plan API access is not in your menu; if you do end up on the screen, you see an explanation and a To Subscription button, not keys.

Where to go

In the left-hand menu, open Settings → API access. Only the Owner role sees this screen.

At the top there are two tabs: Keys and Webhooks. This article is about the first; webhooks are covered in Setting up webhooks.

On the Keys tab you will see three blocks:

1. The connection — the address and the technical description. These are the two details you pass on to whoever builds the integration.
2. New key — this is where you create one.
3. Keys — what already exists, and when it was last used.

Creating a key

Step 1. Give it a name. Not your own name, but the name of whatever sits at the other end: "our website", "bookkeeping", "newsletter". That name is purely for you. It appears in the list, next to "last used". A year from now you will still know which key belongs to what — and which one you can safely revoke.

Step 2. Tick what the key may do. Under What may this key do? you find the permissions, or scopes in jargon. Read is already ticked:

Permission	What the program may do
Read	View your catalogue, prices, free places, discounts, gift vouchers and season passes — and also your orders, tickets, scans and buyers, with their name and email address.
Write	Create orders, have them paid, cancel and refund them, request an invoice, void and resend tickets, check people in, and issue, redeem or renew gift vouchers and season passes.
Webhooks	Arrange for us to send a notification to an address of your own whenever something happens.
Paid externally	Mark an order as paid without a payment provider (bank transfer, cash). Only works together with Write.

Only tick what is genuinely needed. A website that merely has to show which places are free is fine with Read. If that key also gets Write, a bug in that website can create or refund orders you do not want.

Be extra sparing with Paid externally: whoever has it can issue tickets without any money coming in. Only give it to a till or accounting system you manage yourself.

You must tick at least one permission. A key without permissions would be allowed to do nothing, and that is the hardest kind of fault to track down — which is why the screen refuses it.

Step 3 (optional). Set an expiry date. Leave the Expires on (optional) field empty and the key keeps working until you revoke it yourself. Fill in a date and it still works on that day and then stops by itself. The date must lie in the future. Handy when you let someone look in temporarily: you will not have to think about it later.

Step 4 (optional). Test key. Tick Test key (sandbox) for whoever is still building. Such a key reads the same data as a normal one. If it also has Write, it only creates test orders: they never go to your payment provider, do not count towards your revenue and are cleared away automatically after 24 hours. A typing mistake then cannot cause a real payment or refund. A test key cannot set up webhooks.

Note: until it is cleared away, a test order does hold a real place, and the confirmation email really goes out. Have testing done with a product or time slot you create for that purpose.

You recognise a test key by its start: it begins with pv_test_ instead of pv_live_.

Step 5. Click "Create key".

You only see the key once

Right after creating it, the key appears in a box. That is the only time you will see it.

Copy it now and pass it on straight away. Refresh the page and it is gone.

That is not an inconvenience but a protection. We do not keep your key: we keep only a kind of fingerprint of it, which lets us recognise it but not read it back. If someone ever got into our database, that would still give them no access to your data. The flip side is that we cannot show it to you again either.

Lost it? No problem: create a new one and revoke the old one.

Treat a key like a key

Whoever holds the key may do whatever is ticked on it — with no password and without opening your account. So:

• do not send it in an ordinary group chat where it will sit forever;
• do not put it in the visible code of your website;
• give every integration its own key. You can then revoke one without breaking the rest, and the list shows you which one is still in use.

Revoking a key

In the list, click Revoke next to the key and confirm.

From that moment it no longer works. The row stays in the list, marked "Revoked": that way you can still look up later which integration existed when.

Revoke a key when:

• you stop using the tool that was using it;
• you have lost it or it is lying around somewhere;
• someone who had it leaves.

Creating and revoking a key also appears in the activity log of whoever did it (Settings → Staff, that person, Activity tab), with the time. The key itself is never in there.

When was it last used?

Under each key it says when it was last used to fetch something. If it has said "not used yet" for months, there is probably nothing attached to it any more. Go ahead and revoke it — a door nobody uses does not need to stay open.

What you pass on to whoever builds the integration

Three things:

1. the API address from the The connection block;
2. the technical description (the link ending in openapi.json) — a developer sees everything that is possible in one go;
3. the key itself, and which permissions you ticked.

That is all they need.

And then?

You have the address and the key. What happens next is work for whoever builds the integration — and you forward them the developer portal. It holds the full reference, with code examples in four languages and a file that imports straight into Postman or Insomnia.

• What is an API, and do I need one? — if you first want to know what all this is about.
• Webhooks — let your website know something has been sold, without it having to keep asking.
• Setting up webhooks — the Webhooks tab on this same screen, step by step.