---
title: 'API configuration (`providers.yaml`)'
sidebarTitle: 'API configuration'
---
API configurations are listed in the `providers.yaml` file, located in the [Nango GitHub repository](https://github.com/NangoHQ/nango/blob/master/packages/providers/providers.yaml).
## Examples
<Tabs>
<Tab title="Hubspot">
```yaml
hubspot:
display_name: HubSpot
categories:
- marketing
- support
- crm
auth_mode: OAUTH2
authorization_url: https://app.hubspot.com/oauth/authorize
token_url: https://api.hubapi.com/oauth/v1/token
connection_configuration:
- portalId
post_connection_script: hubspotPostConnection
webhook_routing_script: hubspotWebhookRouting
proxy:
base_url: https://api.hubapi.com
decompress: true
paginate:
type: cursor
cursor_path_in_response: paging.next.after
limit_name_in_request: limit
cursor_name_in_request: after
response_path: results
docs: https://nango.dev/docs/api-integrations/hubspot
```
</Tab>
<Tab title="Salesforce">
```yaml
salesforce:
display_name: Salesforce
categories:
- crm
auth_mode: OAUTH2
authorization_url: https://login.salesforce.com/services/oauth2/authorize
token_url: https://login.salesforce.com/services/oauth2/token
authorization_params:
prompt: consent
default_scopes:
- offline_access
token_response_metadata:
- instance_url
proxy:
base_url: ${connectionConfig.instance_url}
webhook_routing_script: salesforceWebhookRouting
post_connection_script: salesforcePostConnection
docs: https://nango.dev/docs/api-integrations/salesforce
connection_config:
instance_url:
type: string
title: Instance URL
description: The instance URL of your Salesforce account
format: uri
pattern: '^https?://.*$'
```
</Tab>
<Tab title="Google">
```yaml
google:
display_name: Google
auth_mode: OAUTH2
authorization_url: https://accounts.google.com/o/oauth2/v2/auth
token_url: https://oauth2.googleapis.com/token
authorization_params:
response_type: code
access_type: offline
prompt: consent
proxy:
base_url: https://www.googleapis.com
paginate:
type: cursor
cursor_path_in_response: nextPageToken
limit_name_in_request: maxSize
cursor_name_in_request: pageToken
response_path: items
docs: https://nango.dev/docs/api-integrations/google
```
</Tab>
<Tab title="Notion">
```yaml
notion:
display_name: Notion
categories:
- knowledge-base
- productivity
auth_mode: OAUTH2
authorization_url: https://api.notion.com/v1/oauth/authorize
token_url: https://api.notion.com/v1/oauth/token
authorization_params:
response_type: code
owner: user
authorization_method: header
body_format: json
proxy:
retry:
after: 'Retry-After'
base_url: https://api.notion.com
headers:
'Notion-Version': '2022-06-28'
paginate:
type: cursor
cursor_path_in_response: next_cursor
cursor_name_in_request: start_cursor
limit_name_in_request: page_size
response_path: results
docs: https://nango.dev/docs/api-integrations/notion
```
</Tab>
<Tab title="Linear">
```yaml
linear:
display_name: Linear
categories:
- productivity
- ticketing
auth_mode: OAUTH2
authorization_url: https://linear.app/oauth/authorize
token_url: https://api.linear.app/oauth/token
scope_separator: ','
authorization_params:
prompt: consent
proxy:
base_url: https://api.linear.app
disable_pkce: true
webhook_routing_script: linearWebhookRouting
post_connection_script: linearPostConnection
webhook_user_defined_secret: true
docs: https://nango.dev/docs/api-integrations/linear
```
</Tab>
<Tab title="Slack">
```yaml
slack:
display_name: Slack
categories:
- productivity
auth_mode: OAUTH2
authorization_url: https://slack.com/oauth/v2/authorize
token_url: https://slack.com/api/oauth.v2.access
token_response_metadata:
- incoming_webhook.url
- incoming_webhook.channel
- incoming_webhook.channel_id
- bot_user_id
- team.id
proxy:
base_url: https://slack.com/api
paginate:
type: cursor
cursor_path_in_response: response_metadata.next_cursor
cursor_name_in_request: cursor
limit_name_in_request: limit
webhook_routing_script: slackWebhookRouting
docs: https://nango.dev/docs/api-integrations/slack
```
</Tab>
</Tabs>
## All configuration fields
<Tip>Looking for the JSON Schema, find it in our [GitHub](https://github.com/NangoHQ/nango/blob/master/scripts/validation/providers/schema.json)</Tip>
<ResponseField name="alias" type="string">
Allows to extend the configuration of another API.
</ResponseField>
<ResponseField name="display_name" type="string" required>
The display name of the provider, used in the UI.
</ResponseField>
<ResponseField name="auth_mode" type="string" >
The authentication mode. Must be one of: "API_KEY", "APP", "APP_STORE", "BASIC", "NONE", "OAUTH1", "OAUTH2", "OAUTH2_CC", "CUSTOM", "TBA", "JWT", "BILL", "TWO_STEP", "SIGNATURE".
</ResponseField>
<ResponseField name="auth" type="object">
Authentication configuration.
<Expandable>
<ResponseField name="response_type" type="string">
The response type for authentication.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="authorization_method" type="string">
The authorization method. Must be `header`
</ResponseField>
<ResponseField name="authorization_params" type="object">
Query parameters of the authorization request.
<Expandable>
<ResponseField name="access_type" type="string">
Possible value: "offline"
</ResponseField>
<ResponseField name="approval_prompt" type="string">
Possible values: "auto", "force"
</ResponseField>
<ResponseField name="duration" type="string">
Possible value: "permanent"
</ResponseField>
<ResponseField name="expiration" type="string">
Possible value: "never"
</ResponseField>
<ResponseField name="force_verify" type="boolean">
Whether to force verification
</ResponseField>
<ResponseField name="nonce" type="string">
A unique string to be included in the request
</ResponseField>
<ResponseField name="prompt" type="string">
Possible value: "consent"
</ResponseField>
<ResponseField name="response_mode" type="string">
The mode of the response
</ResponseField>
<ResponseField name="response_type" type="string">
The type of the response
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="authorization_url" type="string">
The URL to get the OAuth 2 credentials from the external API.
</ResponseField>
<ResponseField name="authorization_url_encoded" type="boolean">
Should the `authorization_url` be encoded or not
</ResponseField>
<ResponseField name="authorization_url_replacements" type="object">
An object containing key-value pairs for replacements in the authorization URL.
</ResponseField>
<ResponseField name="body_format" type="string">
The format of the request body. e.g: `json`
</ResponseField>
<ResponseField name="categories" type="array">
An array of strings representing the categories of the API.
</ResponseField>
<ResponseField name="connection_configuration" type="array">
An array of strings representing the `connectionConfig` that are automatically populated by post-connection functions.
</ResponseField>
<ResponseField name="decode_url" type="boolean">
Whether to decode the URL or not.
</ResponseField>
<ResponseField name="default_scopes" type="array">
The minimum list of scopes that are necessary to connect to the API.
</ResponseField>
<ResponseField name="disable_pkce" type="boolean">
Disables the [PKCE](https://oauth.net/2/pkce/) extension to the Authorization Code flow.
</ResponseField>
<ResponseField name="docs" type="string">
The URL to the developer API documentation.
</ResponseField>
<ResponseField name="docs_connect" type="string">
The URL to the end user documentation (e.g: how to connect).
</ResponseField>
<ResponseField name="post_connection_script" type="string">
The name of the script to run after a connection is established.
</ResponseField>
<ResponseField name="proxy" type="object">
Proxy configuration for the API.
<Expandable>
<ResponseField name="base_url" type="string">
The base URL for the API.
</ResponseField>
<ResponseField name="decompress" type="boolean">
Whether to decompress the response.
</ResponseField>
<ResponseField name="headers" type="object">
Headers to be sent with each request.
</ResponseField>
<ResponseField name="paginate" type="object">
Pagination configuration.
<Expandable>
<ResponseField name="cursor_name_in_request" type="string">
The name of the cursor parameter in the request.
</ResponseField>
<ResponseField name="cursor_path_in_response" type="string">
The path to the cursor value in the response.
</ResponseField>
<ResponseField name="limit_name_in_request" type="string">
The name of the limit parameter in the request.
</ResponseField>
<ResponseField name="link_rel_in_response_header" type="string">
The rel attribute of the link header for pagination.
</ResponseField>
<ResponseField name="link_path_in_response_body" type="string">
The path to the link in the response body.
</ResponseField>
<ResponseField name="offset_name_in_request" type="string">
The name of the offset parameter in the request.
</ResponseField>
<ResponseField name="offset_calculation_method" type="string">
The method to calculate the offset in the request. Must be one of: "per-page" or "by-response-size". Optional parameter that defaults to "by-response-size".
</ResponseField>
<ResponseField name="offset_start_value" type="number">
The starting value for the offset.
</ResponseField>
<ResponseField name="response_path" type="string">
The path to the paginated data in the response.
</ResponseField>
<ResponseField name="type" type="string">
The type of pagination. Must be one of: "link", "cursor", "offset".
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="query" type="object">
Query parameters to be sent with each request.
</ResponseField>
<ResponseField name="retry" type="object">
Retry configuration.
<Expandable>
<ResponseField name="after" type="string">
The name of the rate-limit header, e.g. `after: 'X-Rate-Limit-Reset'`
</ResponseField>
<ResponseField name="at" type="string">
The name of the rate-limit header, e.g. `at: 'x-ratelimit-reset'`
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="verification" type="object" required>
Configure a HTTP call to verify if credentials are valid, only used for API Key and Basic auth.
<Expandable>
<ResponseField name="method" type="string">
The HTTP method for verification. Must be either "GET" or "POST".
</ResponseField>
<ResponseField name="endpoint" type="string" required>
The endpoint for verification.
</ResponseField>
<ResponseField name="base_url_override" type="string">
Override the base URL for verification.
</ResponseField>
<ResponseField name="headers" type="object">
Headers for the verification request.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="redirect_uri_metadata" type="array">
The metadata to capture from the callback request.
</ResponseField>
<ResponseField name="refresh_url" type="string">
The URL used for refreshing the access token. Defaults to the `token_url`
</ResponseField>
<ResponseField name="refresh_params" type="object">
Parameters used for refreshing the access token.
<Expandable>
<ResponseField name="grant_type" type="string">
The grant type for refreshing the token. Must be "refresh_token".
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="request_params" type="object">
An object containing request parameters to pass to an authorization request.
</ResponseField>
<ResponseField name="request_url" type="string">
The URL for making API an authorization request.
</ResponseField>
<ResponseField name="scope_separator" type="string">
The separator used between scopes in the authorization request.
Defaults to space, but some APIs sur `,` or `+`.
</ResponseField>
<ResponseField name="signature_method" type="string">
The signature method used for OAuth 1.0. Must be either "HMAC-SHA1" or "PLAINTEXT".
</ResponseField>
<ResponseField name="token_expiration_buffer" type="number">
A buffer time (in seconds) before the token expiration to trigger a refresh.
</ResponseField>
<ResponseField name="token_params" type="object">
Parameters used for obtaining the access token.
<Expandable>
<ResponseField name="grant_type" type="string">
The grant type for obtaining the token. Must be either "authorization_code" or "client_credentials".
</ResponseField>
<ResponseField name="request" type="string">
Additional request information for obtaining the token.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="token_request_auth_method" type="string">
The authentication method used for token requests. Must be either "basic" or "custom".
</ResponseField>
<ResponseField name="expires_in_unit" type="string">
The unit of time for token expiration. Must be "milliseconds".
</ResponseField>
<ResponseField name="token_response_metadata" type="array">
An array of strings representing metadata from the token response that will be saved in `connection.metadata`.
</ResponseField>
<ResponseField name="token_url" type="string">
The URL to get the OAuth 2 credentials from the external API.
</ResponseField>
<ResponseField name="token_url_encoded" type="boolean">
Should the `token_url` be encoded or not
</ResponseField>
<ResponseField name="webhook_user_defined_secret" type="boolean">
Wether the webhook secret is set by the user.
</ResponseField>
<ResponseField name="webhook_routing_script" type="array">
Specifies a script to handle external [webhooks](/getting-started/use-cases/webhooks-from-external-apis).
</ResponseField>
<ResponseField name="authorization_url_fragment" type="string">
Specifies a fragment to be appended to the authorization URL, typically used to modify the redirection flow or pass additional information in the URL before the query parameters.
</ResponseField>
<ResponseField name="connection_config" type="object">
The list of properties available in `${connectionConfig}` and their validation.
<Expandable>
<ResponseField name="[name]" type="object">
<Expandable>
<ResponseField name="type" type="string" required>
The type of this value. Must be "string".
</ResponseField>
<ResponseField name="title" type="string" required>
The title of this value.
</ResponseField>
<ResponseField name="description" type="string" required>
The description of this value.
</ResponseField>
<ResponseField name="example" type="string">
An example of valid value to display in a UI.
</ResponseField>
<ResponseField name="pattern" type="string">
A regex pattern for the credential.
</ResponseField>
<ResponseField name="format" type="string">
The special format of this value (e.g: `hostname`, `uri`)
</ResponseField>
<ResponseField name="order" type="number">
The order in which this field should be displayed in a UI
</ResponseField>
<ResponseField name="doc_section" type="string">
The documentation section relative to `docs_connect`
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="credentials" type="object">
The list of credentials and their validation, only filed if necessary (e.g: API_KEY, BASIC)
<Expandable>
<ResponseField name="[credential_name]" type="object">
<Expandable>
<ResponseField name="type" type="string" required>
The type of the credential. Must be "string".
</ResponseField>
<ResponseField name="title" type="string" required>
The title of the credential.
</ResponseField>
<ResponseField name="description" type="string" required>
The description of the credential.
</ResponseField>
<ResponseField name="example" type="string">
An example of the credential.
</ResponseField>
<ResponseField name="pattern" type="string">
A pattern for the credential.
</ResponseField>
<ResponseField name="format" type="string">
The format of the credential.
</ResponseField>
<ResponseField name="doc_section" type="string">
The documentation section for the credential.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
<Tip>
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>