Begin a Connection setup session

curl --request POST \
  --url https://api.checkfu.com/v1/principals/{id}/connection-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "offering_id": "<string>",
  "label": "<string>",
  "return_url": "<string>",
  "placement_id": "<string>",
  "scopes": [
    "<string>"
  ],
  "egress_rules": [
    {
      "scheme": "https",
      "host": "<string>",
      "port": 32768,
      "path_prefix": "<string>",
      "methods": [],
      "allowed_headers": [
        "<string>"
      ]
    }
  ]
}
'

import requests

url = "https://api.checkfu.com/v1/principals/{id}/connection-sessions"

payload = {
    "offering_id": "<string>",
    "label": "<string>",
    "return_url": "<string>",
    "placement_id": "<string>",
    "scopes": ["<string>"],
    "egress_rules": [
        {
            "scheme": "https",
            "host": "<string>",
            "port": 32768,
            "path_prefix": "<string>",
            "methods": [],
            "allowed_headers": ["<string>"]
        }
    ]
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    offering_id: '<string>',
    label: '<string>',
    return_url: '<string>',
    placement_id: '<string>',
    scopes: ['<string>'],
    egress_rules: [
      {
        scheme: 'https',
        host: '<string>',
        port: 32768,
        path_prefix: '<string>',
        methods: [],
        allowed_headers: ['<string>']
      }
    ]
  })
};

fetch('https://api.checkfu.com/v1/principals/{id}/connection-sessions', 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.checkfu.com/v1/principals/{id}/connection-sessions",
  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([
    'offering_id' => '<string>',
    'label' => '<string>',
    'return_url' => '<string>',
    'placement_id' => '<string>',
    'scopes' => [
        '<string>'
    ],
    'egress_rules' => [
        [
                'scheme' => 'https',
                'host' => '<string>',
                'port' => 32768,
                'path_prefix' => '<string>',
                'methods' => [
                                
                ],
                'allowed_headers' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>",
    "idempotency-key: <idempotency-key>"
  ],
]);

$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.checkfu.com/v1/principals/{id}/connection-sessions"

	payload := strings.NewReader("{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

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

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("idempotency-key", "<idempotency-key>")
	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.checkfu.com/v1/principals/{id}/connection-sessions")
  .header("checkfu-version", "<checkfu-version>")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/principals/{id}/connection-sessions")

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

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

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

{
  "session": {
    "id": "<string>",
    "workspace_id": "<string>",
    "owner_principal_id": "<string>",
    "connection_id": "<string>",
    "connection_revision_id": "<string>",
    "operation": "connect",
    "flow": {
      "kind": "oauth"
    },
    "status": "pending_runtime",
    "failure": "client_rejected",
    "cleanup_pending": true,
    "expires_at": "<string>",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "next_action": {
    "kind": "open_url",
    "completion": "callback",
    "url": "<string>",
    "expires_at": "<string>"
  }
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Begin a Connection setup session

Begin setup for one exact qualified IntegrationOffering and Principal. Checkfu resolves an opaque placement choice, applies the package’s reviewed scope and egress defaults unless the caller narrows them, reserves immutable Connection and revision identities before adapter I/O, and returns a durable ConnectionSession plus a short-lived trusted-origin URL only when a person must finish OAuth, credential entry, or Bridge pairing. Keep that begin receipt in the reviewed human-completion surface; model-safe follow-up uses getConnectionSession or observeConnectionSession. Requires an Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: connection-lifecycle. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST

principals

{id}

connection-sessions

Begin a Connection setup session

curl --request POST \
  --url https://api.checkfu.com/v1/principals/{id}/connection-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "offering_id": "<string>",
  "label": "<string>",
  "return_url": "<string>",
  "placement_id": "<string>",
  "scopes": [
    "<string>"
  ],
  "egress_rules": [
    {
      "scheme": "https",
      "host": "<string>",
      "port": 32768,
      "path_prefix": "<string>",
      "methods": [],
      "allowed_headers": [
        "<string>"
      ]
    }
  ]
}
'

import requests

url = "https://api.checkfu.com/v1/principals/{id}/connection-sessions"

payload = {
    "offering_id": "<string>",
    "label": "<string>",
    "return_url": "<string>",
    "placement_id": "<string>",
    "scopes": ["<string>"],
    "egress_rules": [
        {
            "scheme": "https",
            "host": "<string>",
            "port": 32768,
            "path_prefix": "<string>",
            "methods": [],
            "allowed_headers": ["<string>"]
        }
    ]
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    offering_id: '<string>',
    label: '<string>',
    return_url: '<string>',
    placement_id: '<string>',
    scopes: ['<string>'],
    egress_rules: [
      {
        scheme: 'https',
        host: '<string>',
        port: 32768,
        path_prefix: '<string>',
        methods: [],
        allowed_headers: ['<string>']
      }
    ]
  })
};

fetch('https://api.checkfu.com/v1/principals/{id}/connection-sessions', 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.checkfu.com/v1/principals/{id}/connection-sessions",
  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([
    'offering_id' => '<string>',
    'label' => '<string>',
    'return_url' => '<string>',
    'placement_id' => '<string>',
    'scopes' => [
        '<string>'
    ],
    'egress_rules' => [
        [
                'scheme' => 'https',
                'host' => '<string>',
                'port' => 32768,
                'path_prefix' => '<string>',
                'methods' => [
                                
                ],
                'allowed_headers' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>",
    "idempotency-key: <idempotency-key>"
  ],
]);

$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.checkfu.com/v1/principals/{id}/connection-sessions"

	payload := strings.NewReader("{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

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

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("idempotency-key", "<idempotency-key>")
	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.checkfu.com/v1/principals/{id}/connection-sessions")
  .header("checkfu-version", "<checkfu-version>")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/principals/{id}/connection-sessions")

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

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offering_id\": \"<string>\",\n  \"label\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"placement_id\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"egress_rules\": [\n    {\n      \"scheme\": \"https\",\n      \"host\": \"<string>\",\n      \"port\": 32768,\n      \"path_prefix\": \"<string>\",\n      \"methods\": [],\n      \"allowed_headers\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

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

{
  "session": {
    "id": "<string>",
    "workspace_id": "<string>",
    "owner_principal_id": "<string>",
    "connection_id": "<string>",
    "connection_revision_id": "<string>",
    "operation": "connect",
    "flow": {
      "kind": "oauth"
    },
    "status": "pending_runtime",
    "failure": "client_rejected",
    "cleanup_pending": true,
    "expires_at": "<string>",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "next_action": {
    "kind": "open_url",
    "completion": "callback",
    "url": "<string>",
    "expires_at": "<string>"
  }
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-24

idempotency-key

string

required

Required string length: 1 - 255

Path Parameters

string

required

Pattern: ^prin_[0-9a-f]{32}$

Body

application/json

offering_id

string

required

Pattern: ^ioff_[0-9a-f]{32}$

label

string

required

Required string length: 1 - 8192

return_url

string

required

Maximum string length: 2048

Pattern: ^https:\/\/[^\s#]+$

placement_id

string

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

scopes

string[]

Required array length: 1 - 256 elements

Required string length: 1 - 512

Pattern: ^[^\s,]+$

egress_rules

object[]

Required array length: 1 - 32 elements

Show child attributes

Response

one open-URL action with the session deadline exactly while human completion is pending

session

object

required

Show child attributes

next_action

object | null

required

Show child attributes

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Begin a Connection setup session

Authorizations

Headers

Path Parameters

Body

Response