Authentication¶
The API uses a member API key on a service account. Create the account, organization, service account, and key at e10s.io. Send the key on every request:
Host: https://api.e10s.io. Paths do not include an organization id. The key is the organization.
Member keys belong to one service account in one organization. They are not your subscribers’ credentials.
Danger
Keep member API keys on servers only. Never ship them in browsers, mobile apps, or other untrusted clients.
Roles¶
A key does what its service account's role allows. You pick the role when you create the service account. Change it later and every key on that account follows. A key has no permissions of its own: for a narrower key, use a service account with a smaller role.
| Role | Can | Use it for |
|---|---|---|
runtime |
GET entitlements, POST check | Production servers. New service accounts get this role. |
viewer |
runtime, plus read features, plans, subscribers, the webhook, and the organization |
Reporting and support tools |
developer |
viewer, plus change features, plans, subscribers, and the webhook |
Catalog and subscriber sync, CI |
admin |
Everything, including members, service accounts, keys, the audit log, and deleting the organization | Infrastructure-as-code |
People have roles too: Console.
Each route needs one label, and a role is a set of labels. A 403 lists the labels the route accepts in details.required_labels.
| Label | Routes | Roles |
|---|---|---|
check |
GET entitlements, POST check | all |
catalog:read |
read features, plans | viewer, developer, admin |
catalog:write |
change features, plans | developer, admin |
subscribers:read |
read subscribers, subscriptions, overrides | viewer, developer, admin |
subscribers:write |
change subscribers, subscriptions, overrides | developer, admin |
webhooks:read |
read the webhook | viewer, developer, admin |
webhooks:write |
set, rotate, pause, resume, delete the webhook | developer, admin |
org:read |
the organization, eval usage, members, service accounts, keys | viewer, developer, admin |
org:write |
rename the organization | admin |
org:members:write |
members, invites | admin |
org:service-accounts:write |
service accounts, keys | admin |
org:delete |
delete the organization | admin |
org:audit:read |
read the audit log | admin |
Mint a key¶
On the service account, Create key: Console. Incoming webhook POSTs are HMAC, not a key: Webhooks.
Rotate keys at e10s.io: create a new key, deploy it, revoke the old one. The plaintext secret is shown once at creation.
What not to send¶
Do not send tokens for your subscribers’ end users to e10s. Authenticate those users in your app, then call e10s with your member key and that customer’s subscriber id.
Failures¶
| HTTP | Meaning |
|---|---|
| 401 | Missing, invalid, or revoked credential |
| 403 | Authenticated, but the key's role doesn't allow this route. See Errors. |
| 404 | Unknown id |
| 429 | Too many requests on GET entitlements + POST check. See Errors. |
A runtime key hitting POST /org/features is 403, not 401. Do not treat that as a broken key.