Authentication and keys
Create organisation API keys, choose their scopes and send them as bearer tokens.
Every call to the API is made with an organisation API key. A key belongs to the organisation rather than to a person, carries its own set of permissions (scopes) and can be revoked at any time.
Creating a key
Only the organisation owner can manage API keys.
- Open Settings > Integrations and choose the API tab.
- Click Create key. Name it after the software that will use it, tick the scopes that software needs and choose how long the key lives.
- Copy the secret from the dialog. It is shown once and never again, so store it in your software's secret store straight away.
An organisation can hold as many keys as it needs: one per system, each with only the scopes that system uses.
Using a key
Send the secret as a bearer token on every request:
Authorization: Bearer nubu_api_...
curl https://app.nubu.app/api/v1/flows \
-H "Authorization: Bearer nubu_api_..."
The key acts as the organisation, not as a person: assets it uploads show no author in the app, and a flow it triggers builds as the organisation.
Scopes
| Scope | Allows |
|---|---|
assets.read | List assets and read their details |
assets.create | Upload new assets |
assets.update | Edit an asset's name, folder and tags |
assets.replace | Upload a new file in place of an existing asset |
assets.delete | Delete assets |
templates.read | List templates and read their details |
templates.create | Upload new template packages |
templates.update | Edit a template's name, folder and tags |
templates.replace | Upload a new package in place of an existing template |
templates.delete | Delete templates |
flows.read | List flows and read their API Trigger |
flows.run | Trigger a flow's API Trigger |
creatives.read | List creatives, read their status, progress, errors and outputs, download renders |
creatives.create | Create creatives |
creatives.update | Edit a creative's fields |
creatives.delete | Delete creatives |
creatives.approve | Approve creatives for rendering |
creatives.rerender | Re-render creatives |
runs.read | Read the runs the API triggered |
A call made with a key that lacks the route's scope answers 403 scope_required, and details.required_scope names the scope to add.
Expiry and revocation
- A key expires at the moment chosen when it was created. An expired key answers
401 invalid_key, and the list marks it Expired. - Revoke a key from the list to stop it immediately; it answers
401 invalid_keyfrom then on. To rotate a key, create the new one first, move your software onto it, then revoke the old one. - The API is a Business+ feature: on any other plan every call answers
403 plan_required.
Signing secret
The same page holds the organisation's signing secret: it is created with your first API key and shown once beside it, and the owner can rotate it there (rotation replaces it at once). Every callback and API Request delivery Nubu sends is signed with it; your endpoints verify X-Nubu-Signature with it (Callbacks).
Outbound credentials
The same tab holds Outbound credentials: the authentication an API Request node sends to your endpoint when it delivers a render. See API Request delivery.