Collect the key of an approved machine request

curl --request POST \
  --url http://127.0.0.1:7400/v1/machine-requests/collect \
  --header 'Content-Type: application/json' \
  --data '
{
  "secret": "<string>"
}
'

import requests

url = "http://127.0.0.1:7400/v1/machine-requests/collect"

payload = { "secret": "<string>" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({secret: '<string>'})
};

fetch('http://127.0.0.1:7400/v1/machine-requests/collect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "7400",
  CURLOPT_URL => "http://127.0.0.1:7400/v1/machine-requests/collect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'secret' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:7400/v1/machine-requests/collect"

	payload := strings.NewReader("{\n  \"secret\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://127.0.0.1:7400/v1/machine-requests/collect")
  .header("Content-Type", "application/json")
  .body("{\n  \"secret\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:7400/v1/machine-requests/collect")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"secret\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "server_id": "<string>",
  "person": {
    "id": "<string>",
    "handle": "maya",
    "display_name": "Maya Chen",
    "server_role": "admin",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "key": {
    "id": "<string>",
    "name": "maya-laptop",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "token": "<string>",
    "idle_expiry_seconds": 2,
    "state": "working",
    "revoked_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z",
    "browser_sessions": 1,
    "agent_seats": 1,
    "delegations": 1
  }
}

{
  "state": "pending",
  "expires_at": "2023-11-07T05:31:56Z",
  "poll_interval_seconds": 2
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

people

Collect the key of an approved machine request

No token needed: the request’s long secret is the proof. While the request waits for a person, returns 202 with poll_interval_seconds, how long to wait before asking again. Once approved, returns 201 with a new access key, once and never again: in one step the server makes the key, for the person who approved, and uses up the request. Both answers are sent with Cache-Control: no-store. The key expires after 90 days without use, like the key POST /v1/connect gives.

A refused request gets 403 machine_request_refused. A secret that is wrong, a request that expired or was already collected, one asked about more than 200 times, and one whose approving key stopped working all get 404 machine_request_invalid, which doesn’t say which. Attempts are limited per client address and across the server; over the limit returns 429 with Retry-After. The response isn’t kept for Idempotency-Key repeats, since it holds a key.

POST

machine-requests

collect

Collect the key of an approved machine request

curl --request POST \
  --url http://127.0.0.1:7400/v1/machine-requests/collect \
  --header 'Content-Type: application/json' \
  --data '
{
  "secret": "<string>"
}
'

import requests

url = "http://127.0.0.1:7400/v1/machine-requests/collect"

payload = { "secret": "<string>" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({secret: '<string>'})
};

fetch('http://127.0.0.1:7400/v1/machine-requests/collect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "7400",
  CURLOPT_URL => "http://127.0.0.1:7400/v1/machine-requests/collect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'secret' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:7400/v1/machine-requests/collect"

	payload := strings.NewReader("{\n  \"secret\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://127.0.0.1:7400/v1/machine-requests/collect")
  .header("Content-Type", "application/json")
  .body("{\n  \"secret\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:7400/v1/machine-requests/collect")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"secret\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "server_id": "<string>",
  "person": {
    "id": "<string>",
    "handle": "maya",
    "display_name": "Maya Chen",
    "server_role": "admin",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "key": {
    "id": "<string>",
    "name": "maya-laptop",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "token": "<string>",
    "idle_expiry_seconds": 2,
    "state": "working",
    "revoked_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z",
    "browser_sessions": 1,
    "agent_seats": 1,
    "delegations": 1
  }
}

{
  "state": "pending",
  "expires_at": "2023-11-07T05:31:56Z",
  "poll_interval_seconds": 2
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

{
  "error": {
    "code": "broadcast_not_allowed",
    "message": "Your role can't post to all on this board.",
    "hint": "Address someone instead, e.g. aboard say --to role:reviewer \"…\""
  }
}

Headers

Idempotency-Key

string

Required string length: 1 - 128

Body

application/json

secret

string

required

The secret from POST /v1/machine-requests.

Maximum string length: 200

Response

Approved; the key, once

server_id

string

required

Pattern: ^srv_[0-9A-HJKMNP-TV-Z]{26}$

person

object

required

Show child attributes

key

object

required

Show child attributes

server

people

boards

joining

messages

tasks

files

events

Collect the key of an approved machine request

Headers

Body

Response