Issue a leased token
curl --request POST \
--url https://api.example.com/connections/{id}/lease-token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"capability_id": "<string>",
"ttl_seconds": 1800,
"scopes": [
"<string>"
]
}
'import requests
url = "https://api.example.com/connections/{id}/lease-token"
payload = {
"capability_id": "<string>",
"ttl_seconds": 1800,
"scopes": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({capability_id: '<string>', ttl_seconds: 1800, scopes: ['<string>']})
};
fetch('https://api.example.com/connections/{id}/lease-token', 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/connections/{id}/lease-token",
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([
'capability_id' => '<string>',
'ttl_seconds' => 1800,
'scopes' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.example.com/connections/{id}/lease-token"
payload := strings.NewReader("{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.example.com/connections/{id}/lease-token")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/connections/{id}/lease-token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"connection_id": "<string>",
"tenant_id": "<string>",
"capability_id": "<string>",
"scopes": [
"<string>"
],
"expires_at": "<string>",
"revoked_at": "<string>",
"created_at": "<string>",
"lease_token": "<string>"
}{
"error": {
"code": "validation_error",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "lease_capability_not_declared",
"message": "<string>",
"details": {}
}
}Connection Leased Tokens
Issue a leased token
Mints a short-TTL bearer token an external service can use to call back into Marfa directly, without holding the connection’s full runtime credential. The capability must be declared on the connection’s integration manifest with oauth_requirements: leased; capabilities not declared as leased reject with 422.
The lease_token field is returned once in the creation response; subsequent reads omit it. See Integrations — OAuth proxy and leased tokens.
POST
/
connections
/
{id}
/
lease-token
Issue a leased token
curl --request POST \
--url https://api.example.com/connections/{id}/lease-token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"capability_id": "<string>",
"ttl_seconds": 1800,
"scopes": [
"<string>"
]
}
'import requests
url = "https://api.example.com/connections/{id}/lease-token"
payload = {
"capability_id": "<string>",
"ttl_seconds": 1800,
"scopes": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({capability_id: '<string>', ttl_seconds: 1800, scopes: ['<string>']})
};
fetch('https://api.example.com/connections/{id}/lease-token', 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/connections/{id}/lease-token",
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([
'capability_id' => '<string>',
'ttl_seconds' => 1800,
'scopes' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.example.com/connections/{id}/lease-token"
payload := strings.NewReader("{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.example.com/connections/{id}/lease-token")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/connections/{id}/lease-token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"capability_id\": \"<string>\",\n \"ttl_seconds\": 1800,\n \"scopes\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"connection_id": "<string>",
"tenant_id": "<string>",
"capability_id": "<string>",
"scopes": [
"<string>"
],
"expires_at": "<string>",
"revoked_at": "<string>",
"created_at": "<string>",
"lease_token": "<string>"
}{
"error": {
"code": "validation_error",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "lease_capability_not_declared",
"message": "<string>",
"details": {}
}
}Authorizations
Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)
Path Parameters
Body
application/json
Response
Lease issued. The lease_token field is returned ONCE; subsequent reads omit it.