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 token never pays for anything, and a 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 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 key your account holds |
A Report key
A 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 key only when its report is stored.
- Public repositories: whoever holds it. Paste the key and the address on your account page. You need no account. Keep the key like a password.
- Private repositories: two accounts at most. The collector spends the key for the account that signs in with the email address that bought it, and for one account the key is added to: yours, or a target's. Surveying a target says how a target uses your key.
- Where to see what it has run. Under Your keys when you are signed in: each survey the 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 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 token accepts
the data processing agreement (version
1.0) for what the collector sends with it.
Each token carries scopes. A request outside them is refused, and the answer names the scope it lacks.
| Scope | Allows | New 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 token left on a
laptop then cannot delete a report or spend a 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 key your account holds. With no key that has days left, the survey is refused and nothing is charged.
How they work together
A private survey needs both: the key pays, and the token says which account is asking.
- Sign in on your account page.
- Add the key to your account, unless you bought it with the address you sign in with.
- Make a 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, and spends the key
A public repository needs only the key, and no token. Architecture shows what runs where in each case.