# Auth patterns

Auth patterns define how Scalekit should authenticate to the upstream API.

Use this page to choose an auth type and build the provider payload for a custom provider.

## Choose an auth type

Bring your own provider supports these auth types:

- OAUTH
- BASIC
- BEARER
- API_KEY

Use OAUTH when the upstream API requires a user authorization flow and token exchange. Use BASIC, BEARER, or API_KEY when the upstream API accepts static credentials or long-lived tokens that Scalekit can attach during proxy calls.

## Understand the provider payload

The provider payload uses these common top-level fields:

- `display_name`: Human-readable name for the custom provider
- `description`: Short description of what the provider connects to
- `auth_patterns`: Authentication options supported by the provider
- `proxy_url`: Base URL the proxy should call for the upstream API (mandatory)
- `proxy_enabled`: Whether the proxy is enabled for the provider (mandatory, should be true)

`proxy_url` can also include templated fields when the upstream API requires account-specific values, for example `https://{{domain}}/api`.

## Understand auth pattern fields

Within `auth_patterns`, the most common fields are:

- `type`: The auth type, such as OAUTH, BASIC, BEARER, or API_KEY
- `display_name`: Label shown for that auth option
- `description`: Short explanation of the auth method
- `fields`: Inputs collected for static auth providers such as BASIC, BEARER, and API_KEY. These usually store values such as `username`, `password`, `token`, `api_key`, `domain`, or `version`.
- `account_fields`: Inputs collected for OAUTH providers when account-scoped values are needed. This is typically used for values tied to a connected account, such as named path parameters.
- `oauth_config`: OAuth-specific configuration, such as authorize and token endpoints
- `auth_header_key_override`: Custom header name when the upstream does not use `Authorization`. For example, some APIs expect auth in a header such as `X-API-Key` instead of the standard `Authorization` header.
- `auth_field_mutations`: Value transformations applied before the credential is sent. This is useful when the upstream expects a prefix, suffix, or default companion value, such as adding a token prefix or setting a fallback password value for Basic auth.

These fields control how Scalekit collects credentials and applies them during proxy calls.

## Example JSON payloads

Use a payload like the following based on the auth pattern you need. In the management flow, you can pass these JSON bodies into the appropriate create or update request.

```json
{
  "display_name": "My Asana",
  "description": "Connect to Asana. Manage tasks, projects, teams, and workflow automation",
  "auth_patterns": [
    {
      "type": "OAUTH",
      "display_name": "OAuth 2.0",
      "description": "Authenticate with Asana using OAuth 2.0 for comprehensive project management",
      "fields": [],
      "oauth_config": {
        "authorize_uri": "https://app.asana.com/-/oauth_authorize",
        "token_uri": "https://app.asana.com/-/oauth_token",
        "user_info_uri": "https://app.asana.com/api/1.0/users/me",
        "available_scopes": [
          {
            "scope": "profile",
            "display_name": "Profile",
            "description": "Access user profile information",
            "required": true
          },
          {
            "scope": "email",
            "display_name": "Email",
            "description": "Access user email address",
            "required": true
          }
        ]
      }
    }
  ],
  "proxy_url": "https://app.asana.com/api",
  "proxy_enabled": true
}
```

```json
{
  "display_name": "My Bearer Token Provider",
  "description": "Connect to an API that accepts a static bearer token",
  "auth_patterns": [
    {
      "type": "BEARER",
      "display_name": "Bearer Token",
      "description": "Authenticate with a static bearer token",
      "fields": [
        {
          "field_name": "token",
          "label": "Bearer Token",
          "input_type": "password",
          "hint": "Your long-lived bearer token",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://api.example.com",
  "proxy_enabled": true
}
```

```json
{
  "display_name": "My Freshdesk",
  "description": "Connect to Freshdesk. Manage tickets, contacts, companies, and customer support workflows",
  "auth_patterns": [
    {
      "type": "BASIC",
      "display_name": "Basic Auth",
      "description": "Authenticate with Freshdesk using Basic Auth with username and password for comprehensive helpdesk management",
      "fields": [
        {
          "field_name": "domain",
          "label": "Freshdesk Domain",
          "input_type": "text",
          "hint": "Your Freshdesk domain (e.g., yourcompany.freshdesk.com)",
          "required": true
        },
        {
          "field_name": "username",
          "label": "API Key",
          "input_type": "text",
          "hint": "Your Freshdesk API Key",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://{{domain}}/api",
  "proxy_enabled": true
}
```

```json
{
  "display_name": "My Attention",
  "description": "Connect to Attention for AI insights, conversations, teams, and workflows",
  "auth_patterns": [
    {
      "type": "API_KEY",
      "display_name": "API Key",
      "description": "Authenticate with Attention using an API Key",
      "fields": [
        {
          "field_name": "api_key",
          "label": "Integration Token",
          "input_type": "password",
          "hint": "Your Attention API Key",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://api.attention.tech",
  "proxy_enabled": true
}
```

## Review the final payload carefully

When you review the final payload, pay close attention to:

- `display_name` and `description`
- The selected auth `type`
- Required `fields` and `account_fields`
- OAuth endpoints and scopes, if the provider uses OAuth
- `proxy_url`

Use the payload body from this page in the create and update requests on the [Managing providers](/agent-auth/bring-your-own-provider/managing-providers) page.