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

# Auth strategies

> A connector can offer several ways to authenticate. You pick one when you connect.

A source system usually accepts more than one kind of credential: a
personal API key, an OAuth app, a service account. Parable models each of
those as an **auth strategy** on the connector definition.

When you add a connector, you choose one strategy and send the fields that
strategy's `configSchema` describes. The instance stores which strategy you
picked (`authenticationStrategy`) and a masked copy of the config.

## How a strategy is described

Each entry in `connector.supportedAuthStrategies` (and on a leaf vendor
grouping) includes:

| Field          | Meaning                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Stable id you pass as `authenticationStrategyId` when you connect.                                                                                          |
| `type`         | The auth method. Values are listed below.                                                                                                                   |
| `label`        | Name shown in setup, such as "Personal API Key".                                                                                                            |
| `configSchema` | The JSON shape of `authenticationConfig` for this strategy. Secret fields are marked so they are stored in Secret Manager, not returned later.              |
| `docs`         | Optional setup notes for this method.                                                                                                                       |
| Method config  | `apiKeyConfig`, `oauth2Config`, `bearerConfig`, and similar. These tell Parable how to send the credential (header name, token URL), not the secret itself. |

Non-secret fields such as a client id can come back on the instance.
Secret values (API keys, client secrets, refresh tokens) are stored
outside the API and come back empty.

## Auth method types

`type` is one of:

| `type`                          | How you authenticate                                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `api_key_header`                | API key or PAT in a header (Linear personal keys, many SaaS tokens).                                             |
| `api_key_query`                 | API key as a query parameter.                                                                                    |
| `bearer`                        | Bearer token in `Authorization` (GitHub PATs).                                                                   |
| `basic`                         | Username and password, HTTP Basic.                                                                               |
| `oauth2_refresh`                | OAuth 2.0 with a refresh token (typical workspace OAuth app).                                                    |
| `oauth2_auth_code_pkce`         | OAuth 2.0 authorization code with PKCE (public clients).                                                         |
| `oauth2_client_credentials`     | OAuth 2.0 client credentials (machine to machine).                                                               |
| `oauth2_jwt_bearer`             | OAuth 2.0 JWT bearer assertion signed with a private key.                                                        |
| `google_domain_wide_delegation` | Google service account with domain-wide delegation.                                                              |
| `session_exchange`              | POST credentials to a sign-in endpoint, then send the session token on later requests (for example Tableau PAT). |
| `session_exchange_jwt`          | Session exchange that mints a JWT.                                                                               |
| `session_exchange_password`     | Session exchange with username and password.                                                                     |
| `custom`                        | Connector-specific. `configSchema` still lists the fields to send.                                               |

A single connector often lists several of these. Linear, for example,
ships a personal API key strategy and OAuth strategies. You pick one per
instance.

Some strategies also have an **ingestion config** schema (which user to
impersonate, which site URL to hit). When `ingestionConfigSchema` is
present, `ingestionConfig` is part of configure. Those values fill URL and
path templates; they do not change how the source is paged. See
[How ingestion walks a source](/connectors/ingestion).

## Configure an instance

Create:

```bash theme={null}
curl -X POST https://api.askparable.com/api/connectors \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "...",
    "groupingId": "...",
    "authenticationStrategyId": "...",
    "authenticationConfig": {},
    "ingestionConfig": {}
  }'
```

Fill `authenticationConfig` from that strategy's `configSchema`. Re-enter
credentials later with `POST /api/connectors/configure`.

For OAuth browser flows, start and complete with
`POST /api/connectors/connector-oauth-start` and
`POST /api/connectors/connector-oauth-complete`.

Validate without saving with `POST /api/connectors/validate`.

If credentials fail later, `GET /api/vendors/tenant-connector-credential-detail`
returns an error code and message, not the secret.

<Note>
  Creating OAuth apps, generating keys, and granting scopes is covered in
  the [product documentation](https://docs.parable.work) for each connector.
</Note>