Keys and tokens
Borehole uses two secrets. A Report key is what you paid for. A collector token lets the collector act for your account. A collector token never pays for anything, and a Report key never signs the collector in.
At a glance
| Report key | Collector token | |
|---|---|---|
| Looks like | ent_… | bh_… |
| What it is | An entitlement: the surveys you paid for | A credential: the collector's sign-in for your account |
| Where it comes from | Your receipt when you buy a Borehole Report, or a free code | Made on your account page, signed in |
| What it allows | 30 days of unlimited surveys from the first: any public repository, and private repositories from two accounts at most | What its scopes allow. A new collector token gets
collect only |
| How long | 30 days from its first survey | Until you revoke it |
| Who can use it | Public repositories: whoever holds it. Private: two accounts at most | Whoever holds it, as your account, within its scopes |
| Pays for a survey | Yes | No. It spends a Report key your account holds |
A Report key
A Report key starts with ent_. It comes in your
receipt when you buy a Borehole Report, or as a free code, which works
the same way. It grants 30 days of unlimited surveys from the first: any public repository, and private repositories from two accounts at most.
- The days start with its first survey, whoever runs it. If that survey fails, they have not started. A survey uses the Report key only when its report is stored.
- Public repositories: whoever holds it. Paste the Report key and the address on your account page. You need no account. Keep the Report key like a password.
- Private repositories: two accounts at most. The collector spends the Report key for the account that signs in with the email address that bought it, and for one account the Report key is added to: yours, or a target's. Surveying a target says how a target uses your Report key.
- Where to see what it has run. Under Your Report keys when you are signed in: each survey the Report key has run, and the days it has left.
- A refund ends it. A refunded or disputed order's key stops working everywhere, and so do the share links made under it.
A collector token
A collector token starts with bh_. You make it on
your account page, and it is shown once: we
store a hash of it, so we cannot show it again. The collector sends it in
each request's Authorization header. Making a collector token accepts
the data processing agreement (version
1.2) for what the collector sends with it.
Each collector token carries scopes. A request outside them is refused, and the answer names the scope it lacks.
| Scope | Allows | New collector tokens |
|---|---|---|
| collect | Send surveys from the collector | Ticked |
| delete | Delete this account's private reports | Not ticked |
| survey | Survey public repositories as this account, spending its key when asked | Not ticked |
Leave only collect
ticked for the collector: it is all the collector needs. A collector token left on a
laptop then cannot delete a report or spend a Report key on a public survey.
- Revoke it on your account page. A revoked token is refused from its next request.
- It is never a payment. A collected survey spends a Report key your account holds. With no Report key that has days left, the survey is refused and nothing is charged.
How they work together
A private survey needs a collector token, which says which account is asking. 3 private surveys in any 30 days are free; beyond them, a Report key pays.
- Sign in on your account page.
- Add the Report key to your account, unless you bought it with the address you sign in with.
- Make a collector token and give it to the collector:
export BOREHOLE_TOKEN=bh_… borehole collect . --dry-run # prints what would be sent, sends nothing borehole collect . # sends it
A public repository needs only the Report key, and no collector token. Architecture shows what runs where in each case.