Keys and permissions

Every request carries a key. Each key belongs to one company, holds only the permissions you gave it, and can expire, be locked to addresses, rolled or revoked.

Secret and publishable keys

KindStartsWhere it goesWhat it can do
Secreteos_sk_Your servers only: environment settings, a secrets manager. Never in a web page or an app people download.Any of the permissions below that you give it.
Publishableeos_pk_Web pages. It only works from the web addresses you list on it.At most read the company profile, read events, create checkouts. Nothing private.

Keys made in your sandbox start eos_sk_test_ and eos_pk_test_, and only work there.

A key looks like eos_sk_12_k3v9q2m7x1ab_…: the kind, your company’s number, the key’s own name, then the secret part. EOS keeps only a keyed fingerprint of the secret part, so a key is shown in full once, when it is made or rolled. After that, Settings shows its first part and last four characters.

Making a key

In EOS, an admin opens Settings, then API keys, and presses Create API key. Give each website, app or system its own key, so you can see what each one does and switch one off without touching the others.

Sending the key

Put it in the Authorization header as a bearer token. If a tool cannot set that header, X-API-Key: eos_sk_… works too. Keys in the address (query string) are never read, because addresses end up in logs.

HTTP
GET /api/v1/events HTTP/1.1
Host: eos.aveoevents.com
Authorization: Bearer eos_sk_12_k3v9q2m7x1ab_…

Permissions

Tick only what a key needs. A request outside its permissions gets 403 with the code missing_scope and the permission it lacked in param. The reference names the permission of every endpoint.

PermissionLets the keyPublishable
company:readRead the company profileName, shop address, currency and contact details.Yes
events:readRead eventsEvents, dates, venues and ticket types with live availability.Yes
events:writePublish eventsPut events on sale or take them off sale.No
checkout:writeCreate checkoutsHold tickets for a buyer and take them to payment.Yes
orders:readRead ordersOrders, items, buyers, payments and totals.No
orders:writeManage ordersCancel, refund, mark paid and resend tickets.No
attendees:readRead guestsTicket holders and whether they are inside.No
attendees:writeUpdate guestsChange a ticket holder's name or email and resend their ticket.No
checkins:readRead check-insEvery scan at the door, with the gate and the result.No
checkins:writeCheck guests inScan tickets in and out at the door.No
discounts:readRead discount codesCodes, their discounts, limits and uses.No
discounts:writeManage discount codesCreate codes on events and remove them.No
enquiries:writeSend enquiriesPass messages from your own contact form into Customer cases.No
reports:readRead sales reportsOrders, tickets and revenue by day.No
webhooks:readRead webhook endpointsEndpoints and their delivery log.No
webhooks:writeManage webhook endpointsAdd, change, test and remove endpoints, and roll their secrets.No

Starting points

When you make a key, Start from ticks the permissions a common use needs. Change them before you create the key, or later.

  • Ticket sales on your websiteShow events and take orders from your own site's server.Secret. company:read, events:read, checkout:write, orders:read, attendees:read
  • Browser (publishable)Safe to put in a web page: events and checkouts only, from your own web addresses.Publishable. company:read, events:read, checkout:write
  • Door scanningYour own scanning app or turnstiles.Secret. events:read, attendees:read, checkins:read, checkins:write
  • Read onlyReporting, a CRM or a data warehouse.Secret. company:read, events:read, orders:read, attendees:read, checkins:read, discounts:read, reports:read, webhooks:read
  • Full accessEverything the API can do.Secret. company:read, events:read, events:write, checkout:write, orders:read, orders:write, attendees:read, attendees:write, checkins:read, checkins:write, discounts:read, discounts:write, enquiries:write, reports:read, webhooks:read, webhooks:write

Expiry

A key can stop working in 7 days, in 30 days, in 90 days, in 6 months, in 1 year, on a day you choose, or never. After that its requests get key_expired. Short lives suit keys for a single event or a contractor; check expires_at on GET /api/v1 to warn yourself in time.

Locking a key down

IP addresses (secret keys)

List your servers’ addresses and the key works from nowhere else. Use single addresses (IPv4 or IPv6) or IPv4 ranges such as 198.51.100.0/24. A request from anywhere else gets ip_not_allowed. Leave the list empty to allow any address.

Web addresses (publishable keys)

A publishable key needs at least one web address, such as https://www.example.com. Browsers send the page’s address with every request, and EOS refuses any other with origin_not_allowed. https://*.example.com allows every subdomain (www, shop and so on) but not example.com itself, so list both if you use both. http://localhost is allowed for building and testing.

Secret keys in a browser

A secret key sent from a web page is refused with secret_key_in_browser, even if it is right, so a key copied into front-end code fails at once instead of quietly leaking.

Request limits

Each key has its own limit of requests a minute: 60, 120, 300, 600 or 1200, 120 unless you choose otherwise. See rate limits for the headers and what to do when you reach it.

Rolling and revoking

  • Roll replaces a key with a new one that has the same name, permissions, limits, addresses and expiry, shown to you once. The old one is revoked at that moment, and webhook endpoints added with it move to the new one. Roll when someone who knew the key leaves, or if it may have been seen.
  • Revoke ends a key for good. Anything using it gets key_revoked.
  • Edit changes a key’s name, permissions, limits, addresses and expiry. Changes apply to its next request.

Making, changing, rolling and revoking keys are written to the company’s audit log with who did it.

Watching your keys

The API keys page shows when each key was last used and from which address, its requests and failures over the last 24 hours, and the latest requests with their status, time taken and request id. Requests are kept for 30 days. Every response carries an X-Request-Id: quote it when you ask AVEO about a request.

Keeping keys safe

  • Keep secret keys in your server’s environment or a secrets manager, never in a code repository, a web page or a mobile app.
  • One key per system, with only the permissions it needs.
  • Lock secret keys to your servers’ IP addresses when they are fixed.
  • Give keys an expiry, and roll them when people with access leave.
  • If a key leaks, roll or revoke it on the API keys page straight away, then check its recent requests.