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

# Authentication

> Auth type reference for OAuth2, custom credentials, and no-auth services

The auth type determines how user credentials are collected, stored, and injected into the service context at call time.

## Auth types

| Type     | Description                                                         | Use case                       |
| -------- | ------------------------------------------------------------------- | ------------------------------ |
| `oauth2` | Full OAuth 2.0 flow with authorization, token exchange, and refresh | GitHub, Google, Slack, Shopify |
| `custom` | User-provided credentials with a configurable settings schema       | API keys, tokens, basic auth   |
| `none`   | No authentication required                                          | Public APIs, data processing   |

## OAuth2

```typescript theme={null}
const SERVICE_CONFIG = {
  displayName: "GitHub",
  description: "GitHub API integration",
  category: "Developer Tools",
  authType: "oauth2",
  authorizationUrl: "https://github.com/login/oauth/authorize",
  tokenUrl: "https://github.com/login/oauth/access_token",
  scopes: "repo user read:org",
  additionalAuthorizationParams: {},
  tokenResponseToCredentials: (response: any) => ({
    accessToken: response.access_token,
    refreshToken: response.refresh_token,
    expiresAt: response.expires_in
      ? Date.now() + response.expires_in * 1000
      : undefined,
    tokenType: response.token_type,
  }),
} as const;
```

| Field                           | Required | Description                                                                           |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `authorizationUrl`              | Yes      | OAuth authorization endpoint                                                          |
| `tokenUrl`                      | Yes      | Token exchange endpoint                                                               |
| `scopes`                        | Yes      | Space-separated OAuth scopes to request                                               |
| `additionalAuthorizationParams` | No       | Extra query parameters for the authorization URL (e.g., `{ access_type: "offline" }`) |
| `tokenResponseToCredentials`    | No       | Maps the provider's token response to the standard credential format                  |

## Custom

```typescript theme={null}
const SERVICE_CONFIG = {
  displayName: "OpenAI",
  description: "OpenAI API integration",
  category: "AI & ML",
  authType: "custom",
} as const;

const CUSTOM_AUTH_SETTINGS = [
  {
    key: "apiKey",
    description: "Your OpenAI API key",
    type: "password",
    required: true,
  },
  {
    key: "organization",
    description: "OpenAI organization ID (optional)",
    type: "text",
    required: false,
  },
] as const;
```

### Custom auth setting fields

| Field          | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `key`          | Unique identifier for the setting                              |
| `description`  | Label shown to the user                                        |
| `type`         | Input type: `text`, `password`, `url`, or `select`             |
| `required`     | Whether the field is required                                  |
| `defaultValue` | Default value (optional)                                       |
| `options`      | JSON-stringified array of `{ value, label }` for `select` type |

### Accessing custom credentials

```typescript theme={null}
createClient(context: AuthenticatedServiceContext<Settings, CustomAuth>) {
  return new OpenAI({
    apiKey: context.userCredentials.customData?.apiKey,
    organization: context.userCredentials.customData?.organization,
  });
}
```

## None

```typescript theme={null}
const SERVICE_CONFIG = {
  displayName: "CSV Parser",
  description: "Parse and transform CSV files",
  category: "Data Processing",
  authType: "none",
} as const;
```

No credentials are collected or injected. The service context still includes the user ID and workspace directory.