Sign in
Integrations

Verify and configure integration credentials

Changed on

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

Request

  • Base URL: https://api.omnara.com/v1
  • URL: https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/integrations/{integrationID}/setup
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Host-omnara_session and API key in header X-Omnara-Csrf

Request body

expected_setup_revisioninteger required
provider_tenant_idstring required
provider_account_refstring

Required GitHub Installation ID. Optional for Discord; an explicitly supplied bot User ID must match the token.

provider_agent_display_namestring

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.

credential_secret_idstring required
provider_configIntegrationProviderConfig

Non-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.

Response

Integration setup.

idstring required
project_idstring required
namestring required

Immutable, project-unique integration name used in config keys and qualified tool names.

integration_kind'slack_thread' | 'discord_thread' | 'github_pr' required

Registered integration implementation; independent of the saved integration's name and immutable ID.

state'active' | 'disconnected' required
setup_revisioninteger required

Credential and transport revision. Launcher edits leave this value unchanged.

last_oauth_flow_idstring
settingsIntegrationSettings required

Integration-owned settings JSON. Validate against capabilities.settings.input_schema from the integration catalog. Public profile references use aprf_ IDs and resolve at runtime.

provider_tenant_idstring

Verified provider identity, omitted until first connection. Retained after disconnect.

provider_account_refstring

Verified provider account, omitted until first connection. Retained after disconnect.

provider_agent_display_namestring required

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.

bot_mentionstring

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.

credential_secret_idstring
provider_configIntegrationProviderConfig required

Non-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.

created_atstring date-time required
updated_atstring date-time required

Changes