> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GL

> Tenant API endpoints for the tenant's external GL connection — read connection state, start a GL connect session, disconnect.

Tenant-side proxy for the GL connection state stored on `tenant.config.gl` in `api-workspace`. Reads the GL adapter's connection state and projects it into a small response shape the `ui-tenant` header consumes for the GL status surface (logo + state dot + last-sync time).

GL config is currently tenant-scoped, so all entities under a tenant share the same GL connection. The header surface lives in the entity layout but reflects tenant-level state.

## GL connection status

```http theme={null}
GET /v1/gl/status
```

Returns the tenant's GL connection (provider, service, status, last-sync). Returns `{ "connected": false }` when the tenant has no GL configured — the header renders a placeholder.

**Response — connected**

```json theme={null}
{
  "connected": true,
  "tenantId": "11111111-…",
  "provider": "unified",
  "service": "xero",
  "status": "ACTIVE",
  "lastSyncAt": "2026-05-08T10:14:00Z",
  "workspaceName": "Fundmin Demo (Xero)"
}
```

**Response — not connected**

```json theme={null}
{ "connected": false, "tenantId": "11111111-…" }
```

| Field           | Notes                                                                 |
| --------------- | --------------------------------------------------------------------- |
| `connected`     | `true` only when `conn.status === "ACTIVE"`.                          |
| `provider`      | The registered GL adapter that owns this connection.                  |
| `service`       | Underlying provider service id (e.g. `"xero"`, `"quickbooks"`).       |
| `status`        | Raw connection status from `api-workspace`.                           |
| `lastSyncAt`    | Latest of `metadata.updated_at` / `metadata.connected_at`, or `null`. |
| `workspaceName` | `metadata.name` (or `metadata.service` fallback).                     |

## Start a GL connect session

```http theme={null}
POST /v1/gl/connect/session
```

Starts a GL connect session for this tenant. The UI opens `sessionUrl` (typically in a popup / new tab); the GL adapter handles the OAuth dance with the underlying provider (Xero / QuickBooks / …) and fires a webhook back to `api-workspace` on success which flips `tenant.config.gl.options.status` to `ACTIVE`. The UI polls `GET /gl/status` after the user completes the connect flow.

**Body**

```json theme={null}
{ "serviceId": "xero" }
```

| Field       | Required | Notes                                                               |
| ----------- | -------- | ------------------------------------------------------------------- |
| `serviceId` | No       | Pre-select a provider in the connect UI. Omit to let the user pick. |

**Response**

```json theme={null}
{
  "sessionUrl": "https://gl-connect.example.com/session/…",
  "consumerId": "tenant-11111111-…"
}
```

## Disconnect

```http theme={null}
DELETE /v1/gl
```

Disconnects the tenant's GL connection. Idempotent — a no-op if there's no connection.

**Response** — `204 No Content`.

## Cross-links

<CardGroup cols={2}>
  <Card title="General ledgers (SDK)" icon="landmark" href="/sdk/capabilities/general-ledgers">
    `ntro.capabilities.gl` — the Python surface workflows use to post journals + bills against the connected GL.
  </Card>

  <Card title="Tenant architecture" icon="sitemap" href="/get-started/tenant-architecture">
    Where the GL connection sits in the cell topology.
  </Card>
</CardGroup>