Verify and configure integration credentials
curl --request POST \
--url https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_setup_revision": 2,
"provider_tenant_id": "<string>",
"credential_secret_id": "<string>",
"provider_account_ref": "<string>",
"provider_agent_display_name": "<string>",
"provider_config": {}
}
'import requests
url = "https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup"
payload = {
"expected_setup_revision": 2,
"provider_tenant_id": "<string>",
"credential_secret_id": "<string>",
"provider_account_ref": "<string>",
"provider_agent_display_name": "<string>",
"provider_config": {}
}
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({
expected_setup_revision: 2,
provider_tenant_id: '<string>',
credential_secret_id: '<string>',
provider_account_ref: '<string>',
provider_agent_display_name: '<string>',
provider_config: {}
})
};
fetch('https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup', 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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup",
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([
'expected_setup_revision' => 2,
'provider_tenant_id' => '<string>',
'credential_secret_id' => '<string>',
'provider_account_ref' => '<string>',
'provider_agent_display_name' => '<string>',
'provider_config' => [
]
]),
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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup"
payload := strings.NewReader("{\n \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup")
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 \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"project_id": "<string>",
"name": "<string>",
"integration_kind": "slack_thread",
"state": "active",
"setup_revision": 2,
"settings": {},
"provider_agent_display_name": "<string>",
"provider_config": {},
"capabilities": {
"tools": {},
"settings": {
"input_schema": {},
"description": "<string>"
},
"subscription": {
"conversation_schema": {}
},
"interaction_handler": {
"input_schema": {},
"description": "<string>"
},
"schedule": {
"input_schema": {},
"description": "<string>"
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_oauth_flow_id": "<string>",
"runtime_failure": {
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z"
},
"provider_tenant_id": "<string>",
"provider_account_ref": "<string>",
"bot_mention": "<string>",
"credential_secret_id": "<string>"
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Integrations
Verify and configure integration credentials
Requires a user principal with project management permission. Slack credentials are configured through OAuth. A stale expected_setup_revision or a credential changed during verification returns 409; reload the integration and retry setup. Setup preserves integration settings; verified provider identity scopes incoming events.
POST
/
orgs
/
{orgID}
/
projects
/
{projectID}
/
integrations
/
{integrationID}
/
setup
Verify and configure integration credentials
curl --request POST \
--url https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_setup_revision": 2,
"provider_tenant_id": "<string>",
"credential_secret_id": "<string>",
"provider_account_ref": "<string>",
"provider_agent_display_name": "<string>",
"provider_config": {}
}
'import requests
url = "https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup"
payload = {
"expected_setup_revision": 2,
"provider_tenant_id": "<string>",
"credential_secret_id": "<string>",
"provider_account_ref": "<string>",
"provider_agent_display_name": "<string>",
"provider_config": {}
}
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({
expected_setup_revision: 2,
provider_tenant_id: '<string>',
credential_secret_id: '<string>',
provider_account_ref: '<string>',
provider_agent_display_name: '<string>',
provider_config: {}
})
};
fetch('https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup', 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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup",
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([
'expected_setup_revision' => 2,
'provider_tenant_id' => '<string>',
'credential_secret_id' => '<string>',
'provider_account_ref' => '<string>',
'provider_agent_display_name' => '<string>',
'provider_config' => [
]
]),
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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup"
payload := strings.NewReader("{\n \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup")
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 \"expected_setup_revision\": 2,\n \"provider_tenant_id\": \"<string>\",\n \"credential_secret_id\": \"<string>\",\n \"provider_account_ref\": \"<string>\",\n \"provider_agent_display_name\": \"<string>\",\n \"provider_config\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"project_id": "<string>",
"name": "<string>",
"integration_kind": "slack_thread",
"state": "active",
"setup_revision": 2,
"settings": {},
"provider_agent_display_name": "<string>",
"provider_config": {},
"capabilities": {
"tools": {},
"settings": {
"input_schema": {},
"description": "<string>"
},
"subscription": {
"conversation_schema": {}
},
"interaction_handler": {
"input_schema": {},
"description": "<string>"
},
"schedule": {
"input_schema": {},
"description": "<string>"
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_oauth_flow_id": "<string>",
"runtime_failure": {
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z"
},
"provider_tenant_id": "<string>",
"provider_account_ref": "<string>",
"bot_mention": "<string>",
"credential_secret_id": "<string>"
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Authorizations
bearerAuthbrowserSessionCookie & csrfHeader
An opaque Omnara personal or organization bearer token.
Path Parameters
Pattern:
^org_[a-z2-7]{26}$Pattern:
^proj_[a-z2-7]{26}$Pattern:
^itg_[a-z2-7]{26}$Body
application/json
Verifies credentials for this saved integration. GitHub tenant/account are the numeric App ID and Installation ID; the secret is github_app_credentials. Discord tenant is the Application ID; its generic secret contains the bot token, from which the bot User ID is discovered automatically. Reconnect preserves the original verified provider identity. A concurrent setup change rejects this request. Credential payloads are never returned.
Required range:
x >= 1Required string length:
1 - 512Pattern:
^sec_[a-z2-7]{26}$Required GitHub Installation ID. Optional for Discord; an explicitly supplied bot User ID must match the token.
Required string length:
1 - 512Optional display label. Discord credential verification defaults to the bot's current name when omitted; cached settings saves preserve the saved label.
Maximum string length:
512Omit to preserve current provider settings. A supplied object replaces them; include every setting you intend to retain.
Response
Integration setup.
Pattern:
^itg_[a-z2-7]{26}$Pattern:
^proj_[a-z2-7]{26}$Immutable, project-unique integration name used in config keys and qualified tool names.
Pattern:
^[a-zA-Z][a-zA-Z0-9-]{0,31}$Registered integration implementation; independent of the saved integration's name and immutable ID.
Available options:
slack_thread, discord_thread, github_pr Available options:
active, disconnected Credential and transport revision. Launcher edits leave this value unchanged.
Required range:
x >= 1Integration-owned settings JSON. Validate against capabilities.settings.input_schema from the integration catalog. Public profile references use aprf_ IDs and resolve at runtime.
Provider account display label, at most 512 UTF-8 bytes. Leading and trailing whitespace is trimmed on save. Empty means no label; an omitted or empty value clears the label on account-management updates.
Maximum string length:
512Non-secret provider configuration, validated for the selected provider. Slack and GitHub integrations require an empty object. Discord accepts only public_key (optional, a 32-byte hex-encoded Ed25519 verification key for interaction callbacks). Omnara manages one Gateway connection per Discord integration. Credentials and integration behavior are not accepted here.
Show child attributes
Show child attributes
Pattern:
^ioaf_[a-z2-7]{26}$Most recent connection failure for the active integration's current setup and credential version. Returned only by Get integration, not list or mutation responses. Omission does not establish provider connectivity; a runtime lease is not a connection check.
Show child attributes
Show child attributes
Verified provider identity, omitted until first connection. Retained after disconnect.
Verified provider account, omitted until first connection. Retained after disconnect.
GitHub App mention including the leading @, derived from the verified App slug. Omitted when the verified slug is unavailable or the integration is not GitHub. Retained after disconnect.
Pattern:
^sec_[a-z2-7]{26}$