OAuthConfigSpecification

Specification describing how an 'advanced' Auth flow would need to function.

type: object

oauth_user_input_from_connector_config_specification

OAuth specific blob. This is a Json Schema used to validate Json configurations used as input to OAuth. Must be a valid non-nested JSON that refers to properties from ConnectorSpecification.connectionSpecification using special annotation 'path_in_connector_config'. These are input values the user is entering through the UI to authenticate to the connector, that might also shared as inputs for syncing data via the connector. Examples: if no connector values is shared during oauth flow, oauth_user_input_from_connector_config_specification=[] if connector values such as 'app_id' inside the top level are used to generate the API url for the oauth flow, oauth_user_input_from_connector_config_specification={ app_id: { type: string path_in_connector_config: ['app_id'] } } if connector values such as 'info.app_id' nested inside another object are used to generate the API url for the oauth flow, oauth_user_input_from_connector_config_specification={ app_id: { type: string path_in_connector_config: ['info', 'app_id'] } }

Required: No
type: object

Examples:

app_id:
  type: string
  path_in_connector_config:
    - app_id

app_id:
  type: string
  path_in_connector_config:
    - info
    - app_id

oauth_connector_input_specification

The DeclarativeOAuth specific blob. Pertains to the fields defined by the connector relating to the OAuth flow.

Interpolation capabilities:

The variables placeholders are declared as {{my_var}}.
The nested resolution variables like {{ {{my_nested_var}} }} is allowed as well.
The allowed interpolation context is:
- base64Encoder - encode to base64, {{ {{my_var_a}}:{{my_var_b}} | base64Encoder }}
- base64Decorer - decode from base64 encoded string, {{ {{my_string_variable_or_string_value}} | base64Decoder }}
- urlEncoder - encode the input string to URL-like format, {{ https://test.host.com/endpoint | urlEncoder}}
- urlDecorer - decode the input url-encoded string into text format, {{ urlDecoder:https%3A%2F%2Fairbyte.io | urlDecoder}}
- codeChallengeS256 - get the codeChallenge encoded value to provide additional data-provider specific authorisation values, {{ {{state_value}} | codeChallengeS256 }}

Examples:

The TikTok Marketing DeclarativeOAuth spec: { "oauth_connector_input_specification": { "type": "object", "additionalProperties": false, "properties": { "consent_url": "https://ads.tiktok.com/marketing_api/auth?{{client_id_key}}={{client_id_value}}&{{redirect_uri_key}}={{ {{redirect_uri_value}} | urlEncoder}}&{{state_key}}={{state_value}}", "access_token_url": "https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/", "access_token_params": { "{{ auth_code_key }}": "{{ auth_code_value }}", "{{ client_id_key }}": "{{ client_id_value }}", "{{ client_secret_key }}": "{{ client_secret_value }}" }, "access_token_headers": { "Content-Type": "application/json", "Accept": "application/json" }, "extract_output": ["data.access_token"], "client_id_key": "app_id", "client_secret_key": "secret", "auth_code_key": "auth_code" } } }
Required: No
type: object
required: ["consent_url","access_token_url"]

consent_url

The DeclarativeOAuth Specific string URL string template to initiate the authentication. The placeholders are replaced during the processing to provide neccessary values.

Required: Yes
type: string

Examples:

https://domain.host.com/marketing_api/auth?{{client_id_key}}={{client_id_value}}&{{redirect_uri_key}}={{{{redirect_uri_value}} | urlEncoder}}&{{state_key}}={{state_value}}

https://endpoint.host.com/oauth2/authorize?{{client_id_key}}={{client_id_value}}&{{redirect_uri_key}}={{{{redirect_uri_value}} | urlEncoder}}&{{scope_key}}={{{{scope_value}} | urlEncoder}}&{{state_key}}={{state_value}}&subdomain={{subdomain}}

scope

The DeclarativeOAuth Specific string of the scopes needed to be grant for authenticated user.
- Required: No
- type: string
Examples:
```
user:read user:read_orders workspaces:read
```
scopes

List of OAuth scope objects. When present, takes precedence over the scope string property. The scope values are joined using the scopes_join_strategy (default: space) before being sent to the OAuth provider.
- Required: No
- type: array
Examples:
```
- scope: user:read
- scope: user:write
```
- items:
  - type: object
  - required: ["scope"]
  - scope
    
    The OAuth scope string to request from the provider.
    - Required: Yes
    - type: string
optional_scopes

Optional OAuth scope objects that may or may not be granted.
- Required: No
- type: array
Examples:
```
- scope: admin:read
```
- items:
  - type: object
  - required: ["scope"]
  - scope
    
    The OAuth scope string to request from the provider.
    - Required: Yes
    - type: string
scopes_join_strategy

The strategy used to join the scopes array into a single string for the OAuth request. Defaults to space per RFC 6749.
- Required: No
- type: string
- default: space
- enum: ["space","comma","plus"]
access_token_url

The DeclarativeOAuth Specific URL templated string to obtain the access_token, refresh_token etc. The placeholders are replaced during the processing to provide neccessary values.
- Required: Yes
- type: string
Examples:
```
https://auth.host.com/oauth2/token?{{client_id_key}}={{client_id_value}}&{{client_secret_key}}={{client_secret_value}}&{{auth_code_key}}={{auth_code_value}}&{{redirect_uri_key}}={{{{redirect_uri_value}} | urlEncoder}}
```
access_token_headers

The DeclarativeOAuth Specific optional headers to inject while exchanging the auth_code to access_token during completeOAuthFlow step.
- Required: No
- type: object
Examples:
```
Authorization: Basic {{ {{ client_id_value }}:{{ client_secret_value }} | base64Encoder }}
```
access_token_params

The DeclarativeOAuth Specific optional query parameters to inject while exchanging the auth_code to access_token during completeOAuthFlow step. When this property is provided, the query params will be encoded as Json and included in the outgoing API request.
- Required: No
- type: object
Examples:
```
'{{ auth_code_key }}': '{{ auth_code_value }}'
'{{ client_id_key }}': '{{ client_id_value }}'
'{{ client_secret_key }}': '{{ client_secret_value }}'
```
extract_output

The DeclarativeOAuth Specific list of strings to indicate which keys should be extracted and returned back to the input config.
- Required: No
- type: array
Examples:
```
- access_token
- refresh_token
- other_field
```
- items:
  - type: string
state

The DeclarativeOAuth Specific object to provide the criteria of how the state query param should be constructed, including length and complexity.
- Required: No
- type: object
- required: ["min","max"]
Examples:
```
min: 7
max: 128
```
- min
  - Required: Yes
  - type: integer
- max
  - Required: Yes
  - type: integer
client_id_key

The DeclarativeOAuth Specific optional override to provide the custom client_id key name, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_client_id_key_name
```
client_secret_key

The DeclarativeOAuth Specific optional override to provide the custom client_secret key name, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_client_secret_key_name
```
scope_key

The DeclarativeOAuth Specific optional override to provide the custom scope key name, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_scope_key_key_name
```
state_key

The DeclarativeOAuth Specific optional override to provide the custom state key name, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_state_key_key_name
```
auth_code_key

The DeclarativeOAuth Specific optional override to provide the custom code key name to something like auth_code or custom_auth_code, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_auth_code_key_name
```
redirect_uri_key

The DeclarativeOAuth Specific optional override to provide the custom redirect_uri key name to something like callback_uri, if required by data-provider.
- Required: No
- type: string
Examples:
```
my_custom_redirect_uri_key_name
```

complete_oauth_output_specification

OAuth specific blob. This is a Json Schema used to validate Json configurations produced by the OAuth flows as they are returned by the distant OAuth APIs. Must be a valid JSON describing the fields to merge back to ConnectorSpecification.connectionSpecification. For each field, a special annotation path_in_connector_config can be specified to determine where to merge it, Examples: complete_oauth_output_specification={ refresh_token: { type: string, path_in_connector_config: ['credentials', 'refresh_token'] } }

Required: No
type: object

Examples:

refresh_token:
  type: string,
  path_in_connector_config:
    - credentials
    - refresh_token

complete_oauth_server_input_specification

OAuth specific blob. This is a Json Schema used to validate Json configurations persisted as Airbyte Server configurations. Must be a valid non-nested JSON describing additional fields configured by the Airbyte Instance or Workspace Admins to be used by the server when completing an OAuth flow (typically exchanging an auth code for refresh token). Examples: complete_oauth_server_input_specification={ client_id: { type: string }, client_secret: { type: string } }

Required: No
type: object

Examples:

client_id:
  type: string
client_secret:
  type: string

complete_oauth_server_output_specification

OAuth specific blob. This is a Json Schema used to validate Json configurations persisted as Airbyte Server configurations that also need to be merged back into the connector configuration at runtime. This is a subset configuration of complete_oauth_server_input_specification that filters fields out to retain only the ones that are necessary for the connector to function with OAuth. (some fields could be used during oauth flows but not needed afterwards, therefore they would be listed in the complete_oauth_server_input_specification but not complete_oauth_server_output_specification) Must be a valid non-nested JSON describing additional fields configured by the Airbyte Instance or Workspace Admins to be used by the connector when using OAuth flow APIs. These fields are to be merged back to ConnectorSpecification.connectionSpecification. For each field, a special annotation path_in_connector_config can be specified to determine where to merge it, Examples: complete_oauth_server_output_specification={ client_id: { type: string, path_in_connector_config: ['credentials', 'client_id'] }, client_secret: { type: string, path_in_connector_config: ['credentials', 'client_secret'] } }

Required: No
type: object

Examples:

client_id:
  type: string,
  path_in_connector_config:
    - credentials
    - client_id
client_secret:
  type: string,
  path_in_connector_config:
    - credentials
    - client_secret

oauth_user_input_from_connector_config_specification​

oauth_connector_input_specification​

complete_oauth_output_specification​

complete_oauth_server_input_specification​

complete_oauth_server_output_specification​

oauth_user_input_from_connector_config_specification

oauth_connector_input_specification

complete_oauth_output_specification

complete_oauth_server_input_specification

complete_oauth_server_output_specification