DryMerge supports creating arbitrary OAuth integrations with gateways and connections. Gateways let you specify a client id and oauth secret as well as a set of scopes that you want to request from the OAuth provider. Connections let individual users go through the OAuth flow to authenticate to a gateway. DryMerge will then handle the OAuth flow for you and allow you to reference the token connection in config.

Setting up an OAuth Integration (Backend)

OAuth integrations are created via constructing a gateway. The easiest way to do this is through our predefined integration templates. If you want to create a custom integration, you can do so by creating a gateway directly.

With Templates

Default Instantiation

client = DryClient(api_key="my-api-key")
client.template(DryId(name='oauth-integration', namespace='airtable', organization='DryMerge', type_='template'), {})

This will initialize the default OAuth integration for Airtable, which will instantiate its values as…

client_id: "{{secrets.airtable_client_id}}"
client_secret: "{{secrets.airtable_client_secret}}"
scopes:
  - data.records:read
  - schema.bases:read

Notably, you must have the secrets airtable_client_id and airtable_client_secret defined in your organization’s secrets. You can do this through the CLI via dry secret upsert --name <secret-name> --value <secret-value>.

Custom Instantiation

If you want to change the values, simply pass in a dictionary with the values you want to change. For example, if you wanted to change the scopes to data.records:read and data.records:write, you would do the following:

client.template(DryId(name='oauth-integration', namespace='airtable', organization='DryMerge', type_='template'), {'scopes': ['data.records:read', 'data.records:write']})

Through the Engine

Check the Engine Reference for information on the OAuth gateway type and how to set it up.

Setting up an OAuth Connection (Backend)

Once you’ve created an OAuth integration, you can set up an Oauth Connection to allow users to authenticate through it. With most end-product templates, this is done implicitly for you if you specify the oauth_gateway argument when instantiating a template. Take this example of instantiating a Google Sheets webhook template:

With End Product Templates

my_user_id = '-exampleid'
client.template(DryId(name='new-spreadsheet-row-webhook', namespace='google', organization='DryMerge', type_='template'), {
    'identifier': f'{my_user_id}',
    # Note the specified gateway here. This will set up an oauth connection called 'google/oauth-exampleid.connection' (`google/oauth` + `my_user_id` + `.connection`)
    'oauth_gateway': 'google/oauth-integration.gateway',
    # Note the use of the connection here with the `access_token` key.
    'access_token': f'{{{{oauth.google/oauth{my_user_id}.connection}}}}',
    'spreadsheet_id': '1PokjiacviBzBGXcVnqqs0-SD8sWCxvKg2l3tLen4AkQ',
    'sheet_name': 'Sheet1',
    'webhook_url': 'https://api.drymerge.com/testing/reflect'
}, my_user_id')

With Custom Config

If you’re writing your own config, the flow is very similar — you’d simply use the hydration syntax to reference the connection’s inner access_token value. For example, if you wanted to use the connection above in a config, you’d do the following:

dry_string:
    access_token: "{{oauth.google/oauth-exampleid.connection}}"

Read more about the engine here.

Using Connections in the SDK

If you’re using the SDK, you can retrieve an access token to directly make requests on behalf of your user by using the oauth token functions and referencing the connection by ID. For example, if you wanted to get the access token for the connection above, you’d do the following:

my_user_id = '-exampleid'
client.oauth_token(DryId(name='oauth{my_user_id}', namespace= 'google', type_='connection'))

Setting Up an OAuth Integration (Frontend)

Setting up an OAuth integration on the frontend is as simple as embedding https://drymerge.com/user/auth in an iframe and passing in your users’ tenant session token. Details are in this guide here.