Create embedded credential session

Create an embedded credential session

curl --request POST \
  --url https://app.rubiehq.com/api/v1/embedded-credential-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "blueprint_keys": [
    "adp-worker-sync",
    "gusto-worker-sync",
    "bamboohr-worker-sync"
  ],
  "parent_origin": "https://app.example.com",
  "name": "Acme Corp HR connection"
}
'

import requests

url = "https://app.rubiehq.com/api/v1/embedded-credential-sessions"

payload = {
    "blueprint_keys": ["adp-worker-sync", "gusto-worker-sync", "bamboohr-worker-sync"],
    "parent_origin": "https://app.example.com",
    "name": "Acme Corp HR connection"
}
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({
    blueprint_keys: ['adp-worker-sync', 'gusto-worker-sync', 'bamboohr-worker-sync'],
    parent_origin: 'https://app.example.com',
    name: 'Acme Corp HR connection'
  })
};

fetch('https://app.rubiehq.com/api/v1/embedded-credential-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://app.rubiehq.com/api/v1/embedded-credential-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([
    'blueprint_keys' => [
        'adp-worker-sync',
        'gusto-worker-sync',
        'bamboohr-worker-sync'
    ],
    'parent_origin' => 'https://app.example.com',
    'name' => 'Acme Corp HR connection'
  ]),
  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://app.rubiehq.com/api/v1/embedded-credential-sessions"

	payload := strings.NewReader("{\n  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\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://app.rubiehq.com/api/v1/embedded-credential-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.rubiehq.com/api/v1/embedded-credential-sessions")

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  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\n}"

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

{
  "id": "ecs_MQ",
  "status": "pending",
  "embed_url": "https://app.rubiehq.com/embed/credential-capture/abc123",
  "blueprint_keys": [
    "adp-worker-sync",
    "gusto-worker-sync",
    "bamboohr-worker-sync"
  ],
  "selected_blueprint_key": null,
  "credential_id": null,
  "parent_origin": "https://app.example.com",
  "expires_at": "2026-08-17T23:00:00.000Z",
  "completed_at": null,
  "created_at": "2026-08-17T22:45:00.000Z"
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

POST

embedded-credential-sessions

Create an embedded credential session

curl --request POST \
  --url https://app.rubiehq.com/api/v1/embedded-credential-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "blueprint_keys": [
    "adp-worker-sync",
    "gusto-worker-sync",
    "bamboohr-worker-sync"
  ],
  "parent_origin": "https://app.example.com",
  "name": "Acme Corp HR connection"
}
'

import requests

url = "https://app.rubiehq.com/api/v1/embedded-credential-sessions"

payload = {
    "blueprint_keys": ["adp-worker-sync", "gusto-worker-sync", "bamboohr-worker-sync"],
    "parent_origin": "https://app.example.com",
    "name": "Acme Corp HR connection"
}
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({
    blueprint_keys: ['adp-worker-sync', 'gusto-worker-sync', 'bamboohr-worker-sync'],
    parent_origin: 'https://app.example.com',
    name: 'Acme Corp HR connection'
  })
};

fetch('https://app.rubiehq.com/api/v1/embedded-credential-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://app.rubiehq.com/api/v1/embedded-credential-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([
    'blueprint_keys' => [
        'adp-worker-sync',
        'gusto-worker-sync',
        'bamboohr-worker-sync'
    ],
    'parent_origin' => 'https://app.example.com',
    'name' => 'Acme Corp HR connection'
  ]),
  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://app.rubiehq.com/api/v1/embedded-credential-sessions"

	payload := strings.NewReader("{\n  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\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://app.rubiehq.com/api/v1/embedded-credential-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.rubiehq.com/api/v1/embedded-credential-sessions")

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  \"blueprint_keys\": [\n    \"adp-worker-sync\",\n    \"gusto-worker-sync\",\n    \"bamboohr-worker-sync\"\n  ],\n  \"parent_origin\": \"https://app.example.com\",\n  \"name\": \"Acme Corp HR connection\"\n}"

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

{
  "id": "ecs_MQ",
  "status": "pending",
  "embed_url": "https://app.rubiehq.com/embed/credential-capture/abc123",
  "blueprint_keys": [
    "adp-worker-sync",
    "gusto-worker-sync",
    "bamboohr-worker-sync"
  ],
  "selected_blueprint_key": null,
  "credential_id": null,
  "parent_origin": "https://app.example.com",
  "expires_at": "2026-08-17T23:00:00.000Z",
  "completed_at": null,
  "created_at": "2026-08-17T22:45:00.000Z"
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "code": "<string>",
        "field": "<string>"
      }
    ]
  }
}

Creates a short-lived iframe URL for the Rubie Embedded Credential Capture widget. Create the session from your backend, return embed_url to the browser, and mount it in an iframe on parent_origin.

curl --fail-with-body -sS \
  "$RUBIE_API_URL/api/v1/embedded-credential-sessions" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connect-user-123" \
  -d '{
    "blueprint_keys": ["adp-worker-sync", "gusto-worker-sync"],
    "parent_origin": "https://app.example.com",
    "name": "Acme Corp HR connection"
  }'

Notes

blueprint_keys is the exact set of Blueprints the user may select. Passing one key skips the picker.
parent_origin must be an allowlisted HTTPS origin with no path, query, or fragment.
Sessions expire after 15 minutes. Create one when the user opens the flow.
Use one idempotency key per deliberate opening. Reusing a key can replay an expired session.
Blueprint branding and its primary authentication strategy are configured in Rubie.

See Embedded Credential Capture for iframe mounting, browser events, and server-side confirmation.

Authorizations

Authorization

string

header

required

Your Rubie API key as a bearer token.

Headers

Idempotency-Key

string

Unique key for safely retrying mutating requests. Matching key + body replays the original response for 24 hours. Matching key + different body returns 409 conflict.

Body

application/json

blueprint_keys

string[]

required

Blueprint keys the end user may select. Passing one key skips the picker and opens that Blueprint's credential form directly.

Required array length: 1 - 50 elements

Example:

[
  "adp-worker-sync",
  "gusto-worker-sync",
  "bamboohr-worker-sync"
]

parent_origin

string<uri>

required

Exact HTTPS origin where the iframe will be mounted. It must be allowlisted for the account and contain no path, query, or fragment.

Maximum string length: 2048

Example:

"https://app.example.com"

name

string

Optional display name for the connection in the Rubie dashboard.

Maximum string length: 256

Response

Embedded credential session created

string

required

Opaque embedded credential session id.

Example:

"ecs_MQ"

status

enum<string>

required

Lifecycle status of an embedded credential session. completed and expired are terminal. Treat this as an open string set and keep polling on statuses you do not recognise.

Available options:

pending,

completed,

expired

blueprint_keys

string[]

required

Exact set of Blueprints displayed in the widget.

Required array length: 1 - 50 elements

parent_origin

string<uri>

required

Exact allowlisted HTTPS origin permitted to frame the widget.

Example:

"https://app.example.com"

expires_at

string<date-time>

required

created_at

string<date-time>

required

embed_url

string<uri> | null

Origin-bound iframe URL. Present while the session is pending and null after it completes or expires.

selected_blueprint_key

string | null

Blueprint selected by the end user. Present when status is completed and guaranteed to belong to blueprint_keys.

credential_id

string | null

Vaulted credential id. Present only when status is completed. Retain it against the initiating user and selected Blueprint.

Example:

"cred_NDc"

completed_at

string<date-time> | null

Credential Sessions

Embedded Credential Sessions

Credentials

Blueprints

Blueprint Runs

Create embedded credential session

Notes

Authorizations

Headers

Body

Response

​Notes

Authorizations

Headers

Body

Response

Notes