Poll an agent access request
An agent polls for the outcome of the access request it made at signup. The handle it was given is the credential, so it is sent only in the JSON body, never in the URL or query string: a request that carries it in the query string is refused with 400 and its access request expires at once, so the agent has to start a new one. No authorization header is used. Poll no faster than every 5 seconds, or the answer is 429 with Retry-After. While the request is pending keep polling. Once an administrator approves it, the first poll that wins the issuing step mints the credential and answers delivered with client_id and client_secret, shown exactly once with Cache-Control: no-store; a poll that loses answers issuing_soon, so poll again. A poll made after delivery revokes the credential and answers revoked. The credential is scoped to the agent setup permissions the administrator was shown, and expires 30 days after approval. Available only while agent access is enabled; otherwise the answer is 404. The credential works only at the identity service’s /token (HTTP Basic client_credentials); a second poll after delivery revokes it at once, and access tokens already minted stay valid until they expire (their lifetime is set by the identity service).
curl --request POST \
--url https://api.fluid.app/api/agent-access/v1/poll \
--header 'Content-Type: application/json' \
--data '
{
"handle": "kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7"
}
'import requests
url = "https://api.fluid.app/api/agent-access/v1/poll"
payload = { "handle": "kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7" }
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({handle: 'kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7'})
};
fetch('https://api.fluid.app/api/agent-access/v1/poll', 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.fluid.app/api/agent-access/v1/poll",
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([
'handle' => 'kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7'
]),
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 := "https://api.fluid.app/api/agent-access/v1/poll"
payload := strings.NewReader("{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\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("https://api.fluid.app/api/agent-access/v1/poll")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/agent-access/v1/poll")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\n}"
response = http.request(request)
puts response.read_body{
"status": "delivered",
"client_id": "client_01h8x2",
"client_secret": "fcs_example_secret"
}{
"status": "unavailable",
"error": "credentials_not_available"
}{}{
"status": "unavailable"
}Body
The handle returned when the access request was made.
Response
The state of the request.
pending awaits an administrator; issuing_soon means the credential is being made, poll again; delivered carries the credential; denied, expired and revoked are final.
pending, issuing_soon, delivered, denied, expired, revoked Present only with delivered.
Present only with delivered, and never shown again.
curl --request POST \
--url https://api.fluid.app/api/agent-access/v1/poll \
--header 'Content-Type: application/json' \
--data '
{
"handle": "kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7"
}
'import requests
url = "https://api.fluid.app/api/agent-access/v1/poll"
payload = { "handle": "kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7" }
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({handle: 'kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7'})
};
fetch('https://api.fluid.app/api/agent-access/v1/poll', 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.fluid.app/api/agent-access/v1/poll",
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([
'handle' => 'kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7'
]),
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 := "https://api.fluid.app/api/agent-access/v1/poll"
payload := strings.NewReader("{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\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("https://api.fluid.app/api/agent-access/v1/poll")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/agent-access/v1/poll")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"kQ3x0m2y7T8v1u4w9Z5a6b7c8d9e0f1g2h3i4j5k6l7\"\n}"
response = http.request(request)
puts response.read_body{
"status": "delivered",
"client_id": "client_01h8x2",
"client_secret": "fcs_example_secret"
}{
"status": "unavailable",
"error": "credentials_not_available"
}{}{
"status": "unavailable"
}