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

# Services Framework overview

> A framework for building external API integrations with platform-managed credentials and authentication

The Synthetiq Services Framework is how external APIs — GitHub, Slack, Shopify, LLM providers, databases, and any other service — are integrated into Synthetiq apps. Each service is a module that defines its authentication requirements and exposes typed tools. The platform handles everything else: OAuth flows, credential storage, token refresh, and per-user authentication.

## What a service is

A service is a self-contained module that wraps an external API. It declares:

* **Authentication type** — OAuth2, custom credentials, or none
* **Configuration settings** — admin-level settings like base URLs or feature flags
* **Tools** — typed functions that call the external API, each with input/output schemas

At runtime, the framework hydrates the service with the authenticated user's credentials and the admin's configuration — the service code never stores, fetches, or manages credentials directly.

## Why the framework manages credentials

In traditional integrations, every application must implement OAuth flows, token storage, refresh logic, and secret management. This creates problems at scale and is especially problematic when AI agents are building the integrations:

| Concern                      | Traditional approach                                        | Synthetiq Services Framework                                  |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| OAuth flows                  | Each app implements authorization, callback, token exchange | Framework handles the full OAuth lifecycle                    |
| Token storage                | Stored in env vars, databases, or config files per app      | Framework stores per-user credentials, isolated from app code |
| Token refresh                | Each app implements refresh logic, handles expiry           | Automatic refresh at request time                             |
| System-wide vs per-user auth | Each app builds multi-user credential management            | Built-in per-user and system-wide credential models           |
| AI agent access              | Agent must manage API keys and tokens                       | Agent calls typed tools, credentials are invisible            |

## Three-tier architecture

Apps call services in their backend routes and workflows via generated, typed service clients. App code does not manage authentication or credentials.

At call time, the framework handles credential hydration based on the current user's authenticated context. It manages OAuth flows for connecting users to services, and can control access to specific services and tools.

The service layer contains the service's configuration (auth type, settings schema) and its implementation code (the actual API calls).

```
┌────────────────────────────────────────────────────┐
│  Application Layer                                 │
│  Apps consume services via generated clients       │
├────────────────────────────────────────────────────┤
│  Framework Layer                                   │
│  Credential hydration, auth flows, access control  │
├────────────────────────────────────────────────────┤
│  Service Layer                                     │
│  Individual services with API-specific logic       │
└────────────────────────────────────────────────────┘
```

### Example: Slack integration

**1. User connects** — The app's settings page includes a connection panel. The user clicks "Connect Slack" and the framework handles the full OAuth flow, storing their credentials securely.

**2. App calls the service** — A backend route calls the generated client with no auth code:

```typescript theme={null}
const channels = await slackClient.listChannels();
```

**3. Framework hydrates credentials** — The framework resolves the current user from the app's auth context, fetches their stored Slack credentials, and injects them into the service.

**4. Service executes** — The Slack service receives the authenticated context and makes the API call to Slack's `conversations.list` endpoint, returning the results to the app.

## Next steps

* [Defining a service](/docs/platform-docs/services-framework/defining-a-service) — create, configure, and build a service
* [Using a service](/docs/platform-docs/services-framework/using-a-service) — generate a client and call services from your app
* [Authentication](/docs/platform-docs/services-framework/authentication) — auth type reference
* [Configuration](/docs/platform-docs/services-framework/configuration) — admin-level service settings
* [Tools](/docs/platform-docs/services-framework/tools) — tool definition reference