Access · Tokens
Give someone access to exactly one action, for as long as you choose
A token is a link that runs only the actions it names. It stops working when it expires, when its uses run out, or when you revoke it. The person holding it needs no account and no key, and every use and every refusal is written to the Ledger.
Tokens are made with a key. Request access and we make the first ones with you.
- Runs
- Open the side gate. Nothing else.
- Works until
- Today, 5:00 PM
- Uses
- 0 of 2
- Account or key
- None needed
- The link
- miscsubjects.com/s/…?token=tk_…
An illustration. The business and the people are made up.
How much detail
Developers: choose “For your developer” for the requests that make, list and revoke tokens.
Example
Let a contractor open one gate, for one afternoon
Press the buttons to use the plumber’s link. Each press is what would happen, and what would be written to the Ledger.
- Clock
- 1:10 PM
- Works until
- 5:00 PM today
- Uses
- 0 of 2
- Revoked
- No
Ledger entries for this link
- Nothing yet. Press “Open the gate”.
A simulation in your browser. Nothing is sent. The reasons for each refusal are the system’s own, in plain words. An illustration. The business and the people are made up.
Example
Refund one customer, up to $500, once
The token decides who may run the action, how many times, and until when. The action’s own permissions decide the amount.
The token
- Runs
- Refund to the original card
- Uses
- 1
- Works until
- 10 minutes after it is made
- Given to
- Your front-desk assistant
The action’s permissions
- Customers
- One customer per refund
- Amount
- Up to $500 without you
What happens
| Asked for | Result |
|---|---|
| $184 to Dana Reyes, order 4821 | Refunded. Use 1 of 1. |
| $184 to Dana Reyes, again | Refused: the token is used up. |
| $750 to another customer, with a new token | Refused: over the $500 limit. Nothing ran. |
| Everyone who booked last month | Refused: one customer per refund. |
An illustration. The business and the people are made up. Every row above is a Ledger entry, the refusals included.
What a token holds
A token names its actions, its expiry and its number of uses
- Actions
- The actions it may run, by name. Nothing else.
- Expiry
- A time, or none: then it works until you revoke it.
- Uses
- A number, or no limit.
- Purpose
- A note of what it is for, kept with it.
- State
- Live, expired, used up or revoked, always visible to you.
A token looks like tk_ followed by 32 letters and digits. A key in a link is never accepted; links carry tokens only.
Making one
One request names the actions, the expiry and the number of uses, and the answer is the ready-made links. Choose “For your developer” to see the requests that make, list and revoke tokens.
Make, list, revoke
curl -X POST https://miscsubjects.com/api/tokens \
-H "x-sheets-key: YOUR_KEY" \
-H "content-type: application/json" \
-d '{"tools": ["NOW"], "ttl_s": 3600, "uses": 1, "purpose": "an example"}'# every token, each live, expired, used up or revoked GET https://miscsubjects.com/api/tokens # one token GET https://miscsubjects.com/api/tokens/TOKEN_ID # revoke it: its links stop working at once POST https://miscsubjects.com/api/tokens/TOKEN_ID/revoke # each with the header x-sheets-key: YOUR_KEY
# the action at its own address https://miscsubjects.com/s/ACTION_NAME?args=…&token=YOUR_TOKEN # the same run, on the run address https://miscsubjects.com/api/run?tool=ACTION_NAME&args=…&token=YOUR_TOKEN # for an AI in a browser whose web tool will not open /api/ addresses https://miscsubjects.com/web/run/ACTION_NAME?args=…&token=YOUR_TOKEN # the Ledger entries of one call made with this token https://miscsubjects.com/web/receipt/CALL_ID?token=YOUR_TOKEN
YOUR_KEYmakes tokens; YOUR_TOKEN is the token itself. ttl_s is its life in seconds (0: until revoked); uses is how many runs it allows (0: no limit).
Refusals
When a token is refused, the answer says why
| Why it was refused | What the answer says | Status |
|---|---|---|
| No token in the link | That this address runs an action with a token. | 401 |
| A token the system never made | No such token. | 401 |
| Revoked | That it was revoked, and when. | 401 |
| Expired | That it expired, and when. | 401 |
| A different action | Which actions the token runs, and that this is not one of them. | 403 |
| Used up | That it is used up, for example 2 of 2 uses. | 429 |
| A key in the link instead of a token | That a key in an address is never accepted. | 400 |
- Each use and each refusal is written to the Ledger.
- The person holding the token can open the Ledger entries of a call they made with it, and only those calls.
Who it is for
Who you might give a token to
A contractor or a cleaner
A gate or a door, for a day, a set number of times.
An assistant
Booking into your calendar, and nothing else.
A partner business
One report, read only, until the end of the month.
Live, read from this site at 11:06 AM.
Give one person one action.
Text us who needs access, to which action, and for how long. We make the token with you.