Choosing a credential
Two credentials reach this API, and they answer different questions.
| API key | OAuth 2.1 | |
|---|---|---|
| Who is it for | Your own backend, acting for your own account | An application acting on behalf of a user, whether your own staff or another company's |
| Setup | Create one in the admin center. Minutes. | Add your app in the admin center, implement the redirect flow. |
| Who consents | Nobody — an account admin issues it | The user, on a consent screen, per scope |
| Identity | The account | The specific user who authorized you |
| Lifetime | Until it expires or is revoked | Access token ~1h, refresh token rotates |
| Where it can be used | Server-side only | Server-side; the flow runs in a browser |
| User interaction | None. Works in cron jobs. | Required for the first authorization |
Pick a key if
- You are Telebroad's customer, automating your own account.
- The integration runs unattended — a nightly export, a webhook receiver, an internal dashboard.
- There is no end user whose permissions should apply.
Pick OAuth if
- You are building something other companies will connect their Telebroad account to.
- Your app should see exactly what the connecting user sees, no more.
- You want per-user consent and per-user revocation, rather than one shared secret.
:::danger Never ship a key in client-side code A key is a bearer credential with no user consent step and no short lifetime. In a mobile app, a browser bundle, or anything a customer can decompile, it is a published password. Use OAuth for anything that runs on someone else's device. :::
What each one is allowed to do
Both are gated by their scopes. They differ in what happens after that check:
- OAuth — the authorizing user's role applies on top. A scope can only narrow what that person could already do in the portal, never widen it. Two tokens on the same account can legitimately return different data.
- API key — today a key carries the whole account within its scopes; there is no user role narrowing it further. See What a key can reach, including the change planned for this.
Both at once is normal
A customer's own backend uses a key, while their staff connect a third-party app over OAuth. Nothing conflicts — the API just sees two credentials with different authority.