Configuring OAuth yourself is required only if you want to use your own OAuth client credentials. Otherwise, Stitch will use its managed credentials to perform the OAuth handshake.

Configuring OAuth allows you to completely white label the source setup process, ensuring your end users have a seamless experience. At a glance, the process will look like this:

  1. Your application handles the OAuth handshake and redirects
  2. Your application provides the required OAuth source properties to the Connect API
  3. Stitch manages OAuth and refresh tokens on an ongoing basis for sources that utilze them

You can configure OAuth for any source with an oauth connection step.

Prerequisites

  • Access to Stitch Connect and valid Connect API credentials. Connect access is a Stitch Advanced or Premium feature. Refer to the Connect API reference for more info on obtaining API credentials.

  • Access to a source with an oauth connection step. This guide will use a Google Analytics SaaS source as an example, but any source type with an oauth connection step will work.

    To determine if a source has an oauth connection step, retrieve its Report Card.

Step 1: Create and configure the source

Create and configure a source. Refer to steps 1-3 of the Create and configure a source using the Connect API guide for instructions.

Note: OAuth properties may be provided in the same request that creates the source, or in a subsequent request to update the source, which is the approach this guide takes.

Step 2: Get the source's OAuth properties

Step Action Endpoint
1 Get the source's report card GET /v4/source-types/{source_type}
2 Understand OAuth property metadata

Step 2.1: Get the source's report card

The OAuth properties that a source uses are found in the oauth step of the source’s report card. Like the form step, these properties will vary from source to source.

To retrieve the source’s OAuth properties, make a request to GET /v4/source-types/{source_type}, replacing {source_type} with the type of the source:

GET /v4/source-types/{source_type}
curl "https://api.stitchdata.com/v4/source-types/platform.google-analytics" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be a Report card object corresponding to the source_type. Locate the OAuth connection step (steps.oauth) property object:

Response for GET /v4/source-types/{source_type}
{
  "type": "platform.google-analytics",
  "current_step": 1,
  "current_step_type": "form",
  "steps": [
    {
      "type": "form",
      "properties": [
        {
          "name": "anchor_time",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "format": "date-time"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "cron_expression",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": null,
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "frequency_in_minutes",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^1$|^30$|^60$|^360$|^720$|^1440$"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "image_version",
          "is_required": true,
          "is_credential": false,
          "system_provided": true,
          "property_type": "read_only",
          "json_schema": null,
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "quota_user",
          "is_required": true,
          "is_credential": false,
          "system_provided": true,
          "property_type": "read_only",
          "json_schema": {
            "type": "string"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "report_definitions",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "name",
                "id"
              ]
            }
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "start_date",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T00:00:00Z$"
          },
          "provided": false,
          "tap_mutable": false
        }
      ]
    },
    {
      "type": "oauth",
      "properties": [
        {
          "name": "client_id",
          "is_required": true,
          "is_credential": true,
          "system_provided": true,
          "property_type": "system_provided_by_default",
          "json_schema": {
            "type": "string"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "client_secret",
          "is_required": true,
          "is_credential": true,
          "system_provided": true,
          "property_type": "system_provided_by_default",
          "json_schema": {
            "type": "string"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "refresh_token",
          "is_required": true,
          "is_credential": true,
          "system_provided": true,
          "property_type": "system_provided_by_default",
          "json_schema": {
            "type": "string"
          },
          "provided": false,
          "tap_mutable": false
        },
        {
          "name": "view_id",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false,
          "tap_mutable": false
        }
      ]
    },
    {
      "type": "discover_schema",
      "properties": []
    },
    {
      "type": "field_selection",
      "properties": []
    },
    {
      "type": "fully_configured",
      "properties": []
    }
  ],
  "details": {
    "pricing_tier": "standard",
    "pipeline_state": "beta",
    "default_start_date": "-1 year",
    "default_scheduling_interval": 60,
    "protocol": "platform.google-analytics",
    "access": true
  }
}

For platform.google-analytics sources, the properties required for OAuth are:

  • client_id

  • client_secret

  • refresh_token

  • view_id

Step 2.2: Understand OAuth property metadata

Next, we’ll touch on the properties an OAuth connection step property contains. You’ll use this data to determine what information you need to provide to successfully configure OAuth for the source.

For OAuth properties, we’ll look at the following metadata:

is_credential
BOOLEAN

If true, the property is a credential or otherwise sensitive data. Note: Values for this property won’t be returned by the API.
is_required
BOOLEAN

If true, the property is required for OAuth configuration.
json_schema
ARRAY

An array containing:

  • type - A string indicating the expected data type of the property’s value. For example: boolean
  • pattern - A string indicating the expected pattern of the property’s value. For example: ^\\d+$
  • anyOf - A series of arrays containing key-value pairs for the type and format combinations Stitch will accept as the property’s value.
name
STRING

The name of the property.
property_type
STRING

Indicates the type of the property. For OAuth properties, possible values are:
provided
BOOLEAN

If true, the property has been provided. For properties where property_type: user_provided, this indicates that you have provided the property.

If a property has an is_required: true value, it must be provided to successfully configure OAuth for the source.

Additionally, consider the property’s property_type value. To configure OAuth using your own OAuth client credentials, you’ll need to provide values for properties where property_type is either user_provided or system_provided_by_default. If you don’t provide a value for properties where property_type: system_provided_by_default, Stitch will use its own OAuth client credentials to perform the OAuth handshake.

Consider the OAuth properties for platform.google-analytics:

OAuth properties for platform.google-analytics
{
  "type": "oauth",
  "properties": [
    {
      "name": "client_id",
      "is_required": true,
      "is_credential": true,
      "system_provided": true,
      "property_type": "system_provided_by_default",
      "json_schema": {
        "type": "string"
      },
      "provided": false,
      "tap_mutable": false
    },
    {
      "name": "client_secret",
      "is_required": true,
      "is_credential": true,
      "system_provided": true,
      "property_type": "system_provided_by_default",
      "json_schema": {
        "type": "string"
      },
      "provided": false,
      "tap_mutable": false
    },
    {
      "name": "refresh_token",
      "is_required": true,
      "is_credential": true,
      "system_provided": true,
      "property_type": "system_provided_by_default",
      "json_schema": {
        "type": "string"
      },
      "provided": false,
      "tap_mutable": false
    },
    {
      "name": "view_id",
      "is_required": true,
      "is_credential": false,
      "system_provided": false,
      "property_type": "user_provided",
      "json_schema": {
        "type": "string"
      },
      "provided": false,
      "tap_mutable": false
    }
  ]
}

As all the properties have an is_required: true value, we’ll need to provide values for every property to configure OAuth.

Step 3: Perform an OAuth handshake with the source

Now that you know what information you need to provide to the Connect API to configure OAuth, you can perform an OAuth handshake with the source.

How you do this is up to you, as implementing an OAuth flow is outside the scope of this guide. We recommend referring to the source’s OAuth documentation, which is included in every source’s connection property reference (if available), for help.

Step 4: Update the source with the OAuth properties

After the OAuth handshake is successfully performed, you can provide the Connect API with the required OAuth properties.

Make a request to PUT /v4/sources/{source_id}, replacing {source_id} with the ID of the source.

The request body should contain a properties object with the required OAuth properties and their values:

PUT /v4/sources/{source_id}
curl -X "PUT" "https://api.stitchdata.com/v4/sources/122635" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json' \
     -d \
'{
   "properties":{
      "client_id":"[GOOGLE_ANALYTICS_CLIENT_ID]",
      "client_secret":"[GOOGLE_ANALYTICS_CLIENT_SECRET]",
      "refresh_token": "[GOOGLE_ANALYTICS_CLIENT_REFRESH_TOKEN]",
      "view_id": "143355753"
   }
}'

The response will be a Source object. If provided, OAuth properties with an is_credential: false value will be included in the properties object. You can also check the OAuth property’s provided value in the OAuth connection step (steps.oauth) property object:

Response for PUT /v4/sources/{source_id}
{
  "properties": {
    "cron_expression": null,
    "frequency_in_minutes": "60",
    "image_version": "0.latest",
    "product": "pipeline",
    "quota_user": "234588",
    "report_definitions": [
      {
        "name": "Visitor Traffic",
        "id": "a53305a5-d6c8-42d3-9c5d-65a524f217c1"
      }
    ],
    "start_date": "2019-03-25T00:00:00Z",
    "view_id": "143355753"
  },
  "updated_at": "2020-06-26T18:06:12Z",
  "schedule": null,
  "name": "tap_google",
  "type": "platform.google-analytics",
  "deleted_at": null,
  "system_paused_at": null,
  "stitch_client_id": 116078,
  "paused_at": "2020-06-23T01:29:17Z",
  "id": 122635,
  "display_name": "Google Analytics",
  "created_at": "2020-03-25T20:23:29Z",
  "report_card": {
    "type": "platform.google-analytics",
    "current_step": 4,
    "current_step_type": "field_selection",
    "steps": [
      {
        "type": "form",
        "properties": [
          {
            "name": "anchor_time",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "format": "date-time"
            },
            "provided": false,
            "tap_mutable": false
          },
          {
            "name": "cron_expression",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": null,
            "provided": false,
            "tap_mutable": false
          },
          {
            "name": "frequency_in_minutes",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^1$|^30$|^60$|^360$|^720$|^1440$"
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "image_version",
            "is_required": true,
            "is_credential": false,
            "system_provided": true,
            "property_type": "read_only",
            "json_schema": null,
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "quota_user",
            "is_required": true,
            "is_credential": false,
            "system_provided": true,
            "property_type": "read_only",
            "json_schema": {
              "type": "string"
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "report_definitions",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "name",
                  "id"
                ]
              }
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "start_date",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T00:00:00Z$"
            },
            "provided": true,
            "tap_mutable": false
          }
        ]
      },
      {
        "type": "oauth",
        "properties": [
          {
            "name": "client_id",
            "is_required": true,
            "is_credential": true,
            "system_provided": true,
            "property_type": "system_provided_by_default",
            "json_schema": {
              "type": "string"
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "client_secret",
            "is_required": true,
            "is_credential": true,
            "system_provided": true,
            "property_type": "system_provided_by_default",
            "json_schema": {
              "type": "string"
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "refresh_token",
            "is_required": true,
            "is_credential": true,
            "system_provided": true,
            "property_type": "system_provided_by_default",
            "json_schema": {
              "type": "string"
            },
            "provided": true,
            "tap_mutable": false
          },
          {
            "name": "view_id",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true,
            "tap_mutable": false
          }
        ]
      },
      {
        "type": "discover_schema",
        "properties": []
      },
      {
        "type": "field_selection",
        "properties": []
      },
      {
        "type": "fully_configured",
        "properties": []
      }
    ]
  }
}

If all form and OAuth connection properties have been provided, the source will advance to the next step in the configuration process. This will typically be field_selection or fully_configured.

Next steps

Congratulations on configuring OAuth for a source! To fully configure a souce, you might also need to select streams and fields to replicate.

Check out the Tutorials and resources to see what else you can do with Stitch Connect.