Secret and publishable keys
| Kind | Starts | Where it goes | What it can do |
|---|---|---|---|
| Secret | eos_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. |
| Publishable | eos_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.
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.
| Permission | Lets the key | Publishable |
|---|---|---|
company:readRead the company profile | Name, shop address, currency and contact details. | Yes |
events:readRead events | Events, dates, venues and ticket types with live availability. | Yes |
events:writePublish events | Put events on sale or take them off sale. | No |
checkout:writeCreate checkouts | Hold tickets for a buyer and take them to payment. | Yes |
orders:readRead orders | Orders, items, buyers, payments and totals. | No |
orders:writeManage orders | Cancel, refund, mark paid and resend tickets. | No |
attendees:readRead guests | Ticket holders and whether they are inside. | No |
attendees:writeUpdate guests | Change a ticket holder's name or email and resend their ticket. | No |
checkins:readRead check-ins | Every scan at the door, with the gate and the result. | No |
checkins:writeCheck guests in | Scan tickets in and out at the door. | No |
discounts:readRead discount codes | Codes, their discounts, limits and uses. | No |
discounts:writeManage discount codes | Create codes on events and remove them. | No |
enquiries:writeSend enquiries | Pass messages from your own contact form into Customer cases. | No |
reports:readRead sales reports | Orders, tickets and revenue by day. | No |
webhooks:readRead webhook endpoints | Endpoints and their delivery log. | No |
webhooks:writeManage webhook endpoints | Add, 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.