enterprise_ai.connectors

Source: sdks/python/src/enterprise_ai/connectors/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class ConnectorsClient

/v1/connectors, /v1/credentials/broker/lease, /v1/webhooks.

Resource

ConnectorsClient.create

create(manifest: dict[str, Any]) -> Any

Register a connector. Applies a Connector manifest: creates or updates the connector (apply_status: created or updated). The URLs must be allowed by the egress policy; OAuth2 needs auth.token_url; unsigned webhooks are refused (422 invalid_manifest). Needs tenant_admin, developer or application_owner. Audited as connector.apply.

Route: /v1/connectors (POST).

Name	Type	Default	Required	Description
manifest	dict[str, Any]		yes	Connector Manifest of the new connector, sent as the request body.

Returns: Any. Decoded JSON answer of the operation "Register a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.delete

delete(name: str) -> Any

Delete a connector. Deletes the connector and its credentials in the secret store. Needs tenant_admin. 404 connector_not_found. Audited as connector.delete.

Route: /v1/connectors/{name} (DELETE).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.

Returns: Any. Decoded JSON answer of the operation "Delete a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.deliver_webhook

deliver_webhook(connector: str, payload: dict[str, Any], secret: str, tenant: str, delivery_id: str | None = None) -> Any

Receive a provider webhook. Entry point for the provider, without platform authentication. Headers: X-EAI-Tenant (tenant slug, else 400 tenant_required), X-EAI-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + raw body>; X-EAI-Timestamp may carry the time), optional X-EAI-Delivery (dedupe id). Steps: 1. The connector must exist, be active and have webhooks enabled (404 connector_not_found). 2. Signature checked with the stored webhook_secret or the manifest secret reference (401 invalid_signature); timestamp within 5 minutes (401 webhook_replay); a delivery already accepted answers 409 webhook_duplicate. 3. The JSON body is screened as untrusted content (prompt injection blocked), then published as connectors.<name>.webhook, which may start triggered runs. Answers 202 with delivery_id, event_id and triggered. Every delivery is recorded and audited as webhook.receive.

Route: /v1/webhooks/{connector} (POST).

Name	Type	Default	Required	Description
connector	str		yes	Name of the connector the provider sends to.
payload	dict[str, Any]		yes	Raw provider payload; the signature is verified on these exact bytes, whatever the content type.
secret	str		yes	Shared webhook secret used for the HMAC-SHA256 signature X-EAI-Signature.
tenant	str		yes	Tenant slug sent as X-EAI-Tenant.
delivery_id	str | None	None	no	Deduplication id sent as X-EAI-Delivery; default dlv- followed by a random hexadecimal id.

Returns: Any. Decoded JSON answer of the operation "Receive a provider webhook".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.get

get(name: str) -> Any

Get a connector. Returns the connector with its manifest, status, owner and configured credentials (kind, field names, update date). 404 connector_not_found.

Route: /v1/connectors/{name} (GET).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.

Returns: Any. Decoded JSON answer of the operation "Get a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.lease

lease(connector: str, scopes: list[str] | None = None, ttl_seconds: int = 300, run_id: str | None = None) -> Any

Obtain a credential lease. Issues a short lived lease on a connector instead of its secret (201): lease_id, token (shown once), scopes, expires_at, ttl_seconds. Requested scopes must be declared by the connector (403 scope_not_allowed; default: all of them); the connector must be active (409 connector_disabled). With on_behalf_of, the user must hold the relation can_invoke on the connector (403 relation_required). Needs tenant_admin, developer or agent. Audited as credential.lease.

Route: /v1/credentials/broker/lease (POST).

Name	Type	Default	Required	Description
connector	str		yes	Name of the connector.
scopes	list[str] | None	None	no	Scopes of the lease, among those the connector declares. Empty (default): all of them.
ttl_seconds	int	300	no	Lifetime of the lease in seconds (30 to 3600, default 600).
run_id	str | None	None	no	Run the lease is issued for, recorded with it.

Returns: Any. Decoded JSON answer of the operation "Obtain a credential lease".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.leased

leased(connector: str, scopes: list[str] | None = None, ttl_seconds: int = 300) -> Iterator[Any]

Context manager yielding a lease; the token is dropped from memory on exit.

Name	Type	Default	Required	Description
connector	str		yes	Name of the connector to lease a token for.
scopes	list[str] | None	None	no	Scopes requested for the delegated token, optional.
ttl_seconds	int	300	no	Lifetime of the lease in seconds (default 300).

Returns: Iterator[Any]. The lease answer of POST /v1/credentials/broker/lease, cleared on exit of the with block.

ConnectorsClient.list

list(**page: Any) -> Any

List the connectors. Connectors of the tenant in name order, each with the kinds of credentials configured (never their values). One page only.

Route: /v1/connectors (GET).

Name	Type	Default	Required	Description
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the connectors".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.set_credentials

set_credentials(name: str, credentials: dict[str, Any]) -> Any

Store connector credentials. Stores credentials in the secret store and returns only the kind and the field names (201). Needs tenant_admin or security_officer. Body: kind plus its fields: - oauth2_client: client_id, client_secret; - oauth2_code: code, redirect_uri, optional code_verifier; the code is exchanged at once at the token URL (needs a stored oauth2_client, else 409 credential_unavailable) and kept as oauth2_token; - api_key: api_key, optional header; - service_account: private_key or token, optional client_email, client_id; - basic: username, password; - webhook_secret: secret. Unknown kinds and missing fields answer 400 invalid_request. Audited as connector.credentials.write.

Route: /v1/connectors/{name}/credentials (POST).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.
credentials	dict[str, Any]		yes	Credentials of the connector, sent write only to the Credential Broker.

Returns: Any. Decoded JSON answer of the operation "Store connector credentials".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.sync

sync(name: str, full: bool = False) -> Any

Start a synchronisation. Queues a sync run (202) and publishes connectors.<name>.sync for the worker. The manifest must declare a sync mode (409 sync_disabled), the connector must be active (409 connector_disabled), resources must be readable (400 invalid_request) and no other run may be queued or running (409 sync_in_progress). An incremental sync starts from the cursor of the last successful run unless full. The policy connector.sync is evaluated. Needs tenant_admin, developer or agent. Audited as connector.sync.

Route: /v1/connectors/{name}/sync (POST).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.
full	bool	False	no	When true, ignore the cursor of the last run and synchronise everything. Default false.

Returns: Any. Decoded JSON answer of the operation "Start a synchronisation".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.sync_runs

sync_runs(name: str) -> Any

List the sync runs of a connector. Synchronisation runs of the connector, newest first: mode, status, resources, cursor and dates.

Route: /v1/connectors/{name}/sync-runs (GET).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.

Returns: Any. Decoded JSON answer of the operation "List the sync runs of a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.test

test(name: str) -> Any

Test a connector. Builds the authentication headers from the stored credentials and, when the manifest has a base URL, sends a GET to it. Returns ok, credentials, http_status, latency_ms and an error code on failure (egress_denied, upstream_unavailable, credential errors); a failed test is a 200 with ok: false. The policy connector.test is evaluated. Needs tenant_admin, developer or application_owner. Audited as connector.test.

Route: /v1/connectors/{name}/test (POST).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.

Returns: Any. Decoded JSON answer of the operation "Test a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.update

update(name: str, **changes: Any) -> Any

Update a connector. Changes the status or the owner. Disabling a connector revokes its credential leases at once. Needs tenant_admin, developer or application_owner. Audited as connector.update.

Route: /v1/connectors/{name} (PATCH).

Name	Type	Default	Required	Description
name	str		yes	Name of the connector.
**changes	Any		no	Fields of the connector to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Update a connector".

Raises: the typed errors of the transport (Errors).

ConnectorsClient.webhook_deliveries

webhook_deliveries(**page: Any) -> Any

List the webhook deliveries. Webhook deliveries received, newest first: connector, delivery id, signature validity, status (accepted, rejected, duplicate), reason, SHA-256 of the payload and published event. The payload itself is not stored here.

Route: /v1/webhooks/deliveries (GET).

Name	Type	Default	Required	Description
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the webhook deliveries".

Raises: the typed errors of the transport (Errors).

Functions

sign_webhook

sign_webhook(secret: str | bytes, payload: bytes, timestamp: int | None = None, tenant: str | None = None, delivery_id: str | None = None) -> dict[str, str]

Headers for a signed webhook pushed to the platform.

Name	Type	Default	Required	Description
secret	str | bytes		yes	Shared webhook secret, text or bytes, the HMAC-SHA256 key.
payload	bytes		yes	Raw body of the request, as bytes.
timestamp	int | None	None	no	Unix time in seconds put in t=; default the current time.
tenant	str | None	None	no	Tenant slug sent as X-EAI-Tenant, optional.
delivery_id	str | None	None	no	Deduplication id sent as X-EAI-Delivery, optional.

Returns: dict[str, str]. Headers X-EAI-Signature, plus X-EAI-Tenant and X-EAI-Delivery when given.

verify_webhook

verify_webhook(secret: str | bytes, payload: bytes, header: str | None, tolerance: int = 300, now: float | None = None) -> bool

Check X-EAI-Signature: t=<unix>,v1=<hex> over "<t>.<raw body>".

Name	Type	Default	Required	Description
secret	str | bytes		yes	Shared webhook secret, text or bytes.
payload	bytes		yes	Raw body received, as bytes.
header	str | None		yes	Value of the X-EAI-Signature header received; None or empty returns False.
tolerance	int	300	no	Maximum gap in seconds between t and now (default 300).
now	float | None	None	no	Current Unix time in seconds; default time.time(), set it in tests.

Returns: bool. True when one v1 signature matches in constant time and the timestamp is fresh, else False.