Authentication
Organisation API keys, scopes and roles.
Send your key as a bearer token on every request:
Authorization: Bearer ik_live_…A key belongs to one organisation, so every call reads and writes that organisation's data and nothing else. You don't send an organisation id.
Who a key acts as
A key acts as the admin who created it, limited by two settings chosen when the key is made:
| Setting | What it limits |
|---|---|
| Role | viewer, programmer or admin. The key gets the lower of this role and its creator's current role. A programmer key cannot do admin-only things even if its creator is an admin. |
| Scopes | Which areas of the API the key may call. A call outside its scopes is refused with 403 SCOPE_DENIED. |
Changes made through the API show up in Ingenee's audit history under the key's creator, together with the key's id. If the creator loses access to the organisation, the key stops working.
Scopes
| Scope | Allows |
|---|---|
library:read | List and read titles, catalogs, rights, images and versions |
library:write | Create, edit, lock, trash and restore titles and catalogs |
imports:write | Import rows, MRSS feeds and S3 sources; stop and resume import jobs |
enrichment:write | Match titles, re-run AI enrichment, decide review-queue suggestions |
studio:read | Read media jobs, media items, subtitles and credit balances |
studio:write | Upload media and start Studio operations (spends media credits) |
vod:read / vod:write | Read / edit storefront pages and shelves, build and publish |
channels:read / channels:write | Read / edit channels, slates and distribution settings |
schedules:write | Generate, edit and publish channel schedules |
ads:read / ads:write | Read / change ad breaks, ad inventory, campaigns and interstitials |
distribution:read / distribution:write | Portals, buyers, deals, licenses and submissions |
feeds:read | Published page, rail, catalog and EPG feeds |
webhooks:write | Add, test and remove webhook endpoints (needs the admin role) |
Each endpoint in the API reference lists the one scope it needs.
Least privilege
Give each system its own key with only the scopes it uses. A storefront that only reads pages needs feeds:read.
Modules
Your organisation's plan decides which modules (Library, VOD, FAST, Studio, Distribution …) it has. A key can't reach
a module the organisation doesn't have. Those calls return 403 MODULE_NOT_ENABLED.
Key lifecycle
- Expiry. A key can be set to expire after 30, 90 or 365 days. After that it returns
401. - Changing access. An admin can change a key's role and scopes at any time without changing the key itself.
- Revoking. A revoked key stops working at once.
- Last used. Settings shows when each key was last used.
Keys are stored hashed. Ingenee can't show a key again, so if you lose one, create a new key and revoke the old one.
Browser use
The API answers CORS requests from any origin, because a key is sent in a header and never as a cookie. That is what lets the API reference's Try it console work. Don't ship a key inside a public web or mobile app. Call Ingenee from your server.