Authentication
Every request carries a bearer token in the Authorization header:
Authorization: Bearer iv_live_ro_...
curl -s https://api.investviews.ai/public/v1/coverage \
-H "Authorization: Bearer {TOKEN}"
There is no OAuth flow, no signed request and no handshake. The token in the header is the credential.
Two endpoints need no token at all: /ping and
/openapi.yaml. You can fetch the whole
contract before you have an account.
Two kinds of token
| Prefix | Capability |
|---|---|
iv_live_rw_ |
read/write |
iv_live_ro_ |
read-only |
Every endpoint in this contract is a read, so either kind works for everything documented
here. A read-only token is refused only on a write endpoint, with 403 read_only_token.
If you are handing a token to something that only ever reads — a dashboard, a scheduled report, an agent — use the read-only one. It cannot become a write credential later by accident.
What each refusal means
Token state maps to the response. These are three different problems and they need three different fixes, which is why they are three different codes.
| State | Response | What to do |
|---|---|---|
| header absent, malformed, unknown, or revoked | 401 invalid_token |
fix or re-issue the token |
| the subscription that owns the token lapsed | 402 subscription_inactive |
fix the billing, not the token |
| this cycle's allowance for the group is spent | 402 quota_exhausted |
wait for the reset, or upgrade |
| a read-only token on a write endpoint | 403 read_only_token |
use a read/write token |
Why a lapsed plan is 402 and not 401
A 401 says "your credential is not usable" and sends an engineer to re-issue a token.
But the token was never the problem — it is still yours, and a new one will fail exactly
the same way. 402 says the account cannot pay for the call, which is a billing
problem with a billing fix. Collapsing the two would send people to the wrong place
every time.
Both 402s are payment states, but they are still distinct: subscription_inactive means
the plan lapsed, quota_exhausted means the plan is fine and this cycle's requests are
spent. See Quota.
Revocation takes effect immediately
Tokens are created and revoked on the API tokens page of your InvestViews account, which also lists every token you hold and what it has spent.
The token row is re-read on every request and never cached. Revoke a token and the very next call using it is refused — there is no propagation delay to wait out, and no window in which a leaked token still works.
A revoked token stays in that list, marked revoked, rather than disappearing: it is the record that a rotation happened.
The same fact costs you something: a token cannot be validated once and trusted for a batch. Every request stands alone.
Handling a token safely
- Put it in the header, never the URL. Query strings end up in access logs, browser
history, proxy logs and
Refererheaders. A header does not. - Do not commit it. Read it from the environment or a secret store.
- Give each consumer its own token. Then revoking one does not take down the others, and
/usagetells you what each is spending. Name it after the app or agent when you create it, so the one to revoke is obvious later. - Prefer read-only wherever it fits.
- Copy it when it is shown. The plaintext appears exactly once, on the API tokens page, at the moment you create it. It is never shown again and cannot be recovered — if you lose it, revoke that token and create another.
The API playground uses a real token
The reference page sends real requests against production. A token
pasted there spends real quota against real data. It is not routed through any third
party — the playground talks to api.investviews.ai directly — but it is a live call.