Resolve a provider member to a Principal

curl --request POST \
  --url https://api.checkfu.com/v1/external-identities/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "external_installation_id": "<string>",
  "external_user_id": "<string>",
  "display_name": "<string>",
  "attributes": {}
}
'

import requests

url = "https://api.checkfu.com/v1/external-identities/resolve"

payload = {
    "external_installation_id": "<string>",
    "external_user_id": "<string>",
    "display_name": "<string>",
    "attributes": {}
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "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>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_installation_id: '<string>',
    external_user_id: '<string>',
    display_name: '<string>',
    attributes: {}
  })
};

fetch('https://api.checkfu.com/v1/external-identities/resolve', 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/external-identities/resolve",
  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([
    'external_installation_id' => '<string>',
    'external_user_id' => '<string>',
    'display_name' => '<string>',
    'attributes' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$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/external-identities/resolve"

	payload := strings.NewReader("{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}")

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

	req.Header.Add("checkfu-version", "<checkfu-version>")
	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/external-identities/resolve")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/external-identities/resolve")

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

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}"

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

{
  "link": {
    "id": "<string>",
    "workspace_id": "<string>",
    "external_installation_id": "<string>",
    "external_user_id": "<string>",
    "principal_id": "<string>",
    "display_name": "<string>",
    "attributes": {},
    "state": "active",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "principal": {
    "id": "<string>",
    "workspace_id": "<string>",
    "external_subject_id": "<string>",
    "principal_type": "person",
    "display_name": "<string>",
    "attributes": {},
    "status": "active",
    "resource_version": 4503599627370495,
    "created_at": "<string>",
    "updated_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"
  }
}

Resolve a provider member to a Principal

Create-or-return the ExternalIdentityLink for one provider member under an ExternalInstallation, returning both the link and its resolved Principal. Identity keys on (external_installation_id, external_user_id) and never on display name or email, so identical user-shaped values under two installations resolve to distinct Principals. The first resolve for an unseen member may mint a person Principal; every later resolve returns the linked one and refreshes only display metadata. You are the trusted asserter — verify the provider event before calling.

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

POST

external-identities

resolve

Resolve a provider member to a Principal

curl --request POST \
  --url https://api.checkfu.com/v1/external-identities/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "external_installation_id": "<string>",
  "external_user_id": "<string>",
  "display_name": "<string>",
  "attributes": {}
}
'

import requests

url = "https://api.checkfu.com/v1/external-identities/resolve"

payload = {
    "external_installation_id": "<string>",
    "external_user_id": "<string>",
    "display_name": "<string>",
    "attributes": {}
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "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>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_installation_id: '<string>',
    external_user_id: '<string>',
    display_name: '<string>',
    attributes: {}
  })
};

fetch('https://api.checkfu.com/v1/external-identities/resolve', 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/external-identities/resolve",
  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([
    'external_installation_id' => '<string>',
    'external_user_id' => '<string>',
    'display_name' => '<string>',
    'attributes' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$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/external-identities/resolve"

	payload := strings.NewReader("{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}")

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

	req.Header.Add("checkfu-version", "<checkfu-version>")
	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/external-identities/resolve")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/external-identities/resolve")

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

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_installation_id\": \"<string>\",\n  \"external_user_id\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"attributes\": {}\n}"

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

{
  "link": {
    "id": "<string>",
    "workspace_id": "<string>",
    "external_installation_id": "<string>",
    "external_user_id": "<string>",
    "principal_id": "<string>",
    "display_name": "<string>",
    "attributes": {},
    "state": "active",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "principal": {
    "id": "<string>",
    "workspace_id": "<string>",
    "external_subject_id": "<string>",
    "principal_type": "person",
    "display_name": "<string>",
    "attributes": {},
    "status": "active",
    "resource_version": 4503599627370495,
    "created_at": "<string>",
    "updated_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

Maximum string length: 255

Body

application/json

external_installation_id

string

required

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

external_user_id

string

required

Required string length: 1 - 512

display_name

string

Required string length: 1 - 255

attributes

object

Show child attributes

Response

Success

link

object

required

Show child attributes

principal

object

required

One Workspace Principal and its public identity attributes.

Show child attributes

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Resolve a provider member to a Principal

Authorizations

Headers

Body

Response