Connections

Get connection

Returns one connection. Status is refreshed on read. Connections the caller cannot see answer 404, never 403, including another member's private connection: the caller must own the connection or hold a grant on it (directly, through a team, or org-wide), even if they hold connection:manage. can_share, can_manage and can_transfer say whether the caller may share, edit, or transfer or delete the connection; only ownership or a grant reaches them (see the schema for each). access_summary, a short summary of who has access, is present only when can_share is true; page GET /connection/{id}/share for the grants themselves.

get/connection/{id}

Request

  • Base URL: https://api.elaichi.ai
  • URL: https://api.elaichi.ai/connection/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Connection id (conn_…).

Headers

X-Organization-Idstring

Target organization (org_…). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.

Response

OK

idstring

Connection id (conn_…).

connector_slugstring

Which connector this account is on.

namestring
owner_user_idstring

Owning member (usr_…); calls run as this identity. The owner has implicit edit, plus delete and transfer, which no share confers. Move it with POST /connection/{id}/transfer. This is who is accountable for the connection now, which after a transfer is not who authenticated it; see connected_by_user_id.

connected_by_user_idstring nullable

Who authenticated this account (usr_…): the member whose third-party credential Elaichi holds. Written once at creation and never rewritten. It differs from owner_user_id on purpose: POST /connection/{id}/transfer moves the owner and does not touch the stored credential, so after a transfer these are two different people and only this one should be shown as "Connected by". Null means not recorded, never "nobody": connections created before this field existed are null. Show nothing for a null.

connected_by_labelstring nullable

Display name for connected_by_user_id (name, else email). Present on every response that returns a connection, commands included. A null label beside a non-null connected_by_user_id means the person has left the organization; show "Former member". Compare the two fields, never one alone: a null id means "not recorded", a null label means "departed".

saffron_account_idstring nullable

Identifier of the stored credential Elaichi holds for this connection. Opaque; null until the connect flow completes.

status'pending' | 'active' | 'needs_reauth' | 'disconnected'

pending = created but not yet authenticated (open connect_url); active = usable; needs_reauth = the credential expired or was revoked upstream, call reconnect; disconnected = no longer usable. Refreshed when connections are read.

last_errorstring nullable
accessstring

The caller's relationship to this connection: owner, or a granted view/use/edit level. A connection the caller neither owns nor holds a grant on is not visible to them at all, whatever organization permission they hold.

created_atstring date-time
updated_atstring date-time
can_shareboolean

Whether the caller may share this connection: the owner, edit access, or a team admin on a team-granted one, and connection:share. Computed by the API, so read it rather than re-deriving it from owner_user_id and permissions.

can_manageboolean

Present on every list and detail row. Whether the caller may edit this connection's own settings: the owner, or edit access.

can_transferboolean

Present on every list and detail row. Whether the caller may transfer or delete this connection: the owner only. Narrower than can_manage, because an edit grant lets someone use and reconfigure a connection, never give it away or destroy it.

can_revoke_shareboolean

Present on every list and detail row. Whether the caller may grant or revoke access to this connection. It matches can_share and is separate from can_manage: an edit grantee whose role omits connection:share can reconfigure or reconnect the connection but cannot change who else has access. Mirrors DELETE /connection/{id}/share/{aclId}.

access_via'owner' | 'direct' | 'team' | 'org'

How the caller reaches this connection, not who else can. owner: they own it. direct: a grant names them personally. team: a grant to a team they belong to (or administer), named in access_via_team. org: an organization-wide grant. When several sources apply, the broadest wins and the access level plays no part: owner, else org, else team, else direct. A caller with edit personally and view org-wide reads org, because this field says how far the connection reaches, not what the caller may do with it. It describes only the caller's own access, so a view or use grantee still gets it while the list of other grantees stays hidden. Absent when nothing reaches the caller (for example, the former owner after a transfer of a resource that was never shared); absent never means org.

Changes

No recorded changes to this operation across all 1 revision of this API.