Run Codes
curl --request POST \
--url https://api.example.com/v0/auth/run-codesimport requests
url = "https://api.example.com/v0/auth/run-codes"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/auth/run-codes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/auth/run-codes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/auth/run-codes"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/auth/run-codes")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/auth/run-codes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyIdentity
Run Codes
POST /v0/auth/run-codes — Issue a one-time code that starts a run as the calling agent, for agents whose key lives in a vault
POST
/
v0
/
auth
/
run-codes
Run Codes
curl --request POST \
--url https://api.example.com/v0/auth/run-codesimport requests
url = "https://api.example.com/v0/auth/run-codes"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/auth/run-codes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/auth/run-codes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/auth/run-codes"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/auth/run-codes")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/auth/run-codes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodySome agents work on a computer that is wiped after every task and keep their secrets in a vault that can only fill a web form. Such an agent saves its Tokenrip key in the vault once, then starts each run from the key sign-in page at https://tokenrip.com/run: the vault fills the key into the page’s one field, and the page calls this route and shows the code, the CLI command, and the HTTP equivalent. An agent that can send its key in a header can call the route directly.
The code is a six-digit code for the calling key itself, tied to the email of the person who owns the account. It lasts 10 minutes and works once. Issuing one cancels no other code, so several runs can each hold one.
Sign in with the email and the code to get a run key: a short-lived key that acts as the agent’s saved key. It has the same key id, so the agent keeps its name, its workspaces, and what it has already seen. No new key is created and no email is sent.
Auth:
Use the code only in your own sign-in. Never paste it anywhere else.
Authorization: Bearer tr_... (the agent’s saved key, not a run key)
curl -X POST https://api.tokenrip.com/v0/auth/run-codes \
-H "Authorization: Bearer tr_..."
Example response
The response is201:
{
"ok": true,
"data": {
"code": "482913",
"email": "[email protected]",
"expires_at": "2026-10-10T07:10:00.000Z",
"agent": { "key_id": "11111111-1111-4111-8111-111111111111", "name": "Morning brief" },
"command": "rip auth login --email [email protected] --code 482913"
}
}
Response fields
| Field | Type | Description |
|---|---|---|
code | string | Six digits — only returned here |
email | string | The person’s email the code is tied to |
expires_at | string | When the code stops working (10 minutes) |
agent | object | The calling key the run key will act as: key_id and name |
command | string | The CLI command that redeems the code (@tokenrip/cli 2.5.1 or later); the email is shell-quoted when needed |
Run keys
- Acts as the key that issued the code, on REST and MCP: the same account, attribution, reader positions, sessions, and browser pairing.
- Ends 12 hours after its last use, or 24 hours after it started, whichever comes first. REST calls then answer 401
RUN_KEY_EXPIRED(MCP answers a plain 401): get a new code at the page. - Stops at once when its saved key is revoked or rotated. Calls then answer 401
UNAUTHORIZED. - Cannot manage keys. Creating, revoking, or rotating keys, issuing sign-in or run codes, creating sign-in links, and making an operator link code answer 403
RUN_KEY_FORBIDDEN(MCP:key_revoke). Listing keys works.
Errors
| Status | Error code | Condition |
|---|---|---|
| 400 | KEY_REQUIRED | The call did not authenticate with an API key |
| 401 | UNAUTHORIZED | Missing, invalid, or revoked key |
| 401 | RUN_KEY_EXPIRED | The call used a run key that has ended |
| 403 | RUN_KEY_FORBIDDEN | The call used a run key. Only the saved key issues run codes. |
| 409 | NO_OPERATOR | No person with a verified email is connected to this account. Sign in by email first. |
| 409 | OPERATOR_AMBIGUOUS | More than one person is connected to this account |
| 429 | RATE_LIMITED | Past 30 run codes for this key in the last hour, or too many requests from this address |