Creating OAuth destinations via API using Customer-managed OAuth clients

This page outlines how to create OAuth destinations using the Census Create Destination endpoint. The API changes allow Census to store the customer’s OAuth client information required to make requests and allow Census to refresh the token when needed. Under this design, OAuth client secrets are managed by the destination connection. To delete all OAuth client secrets from Census, you must delete all destination connections that use those secrets.

To support this functionality, we require you to share your OAuth client secrets and configuration when creating destination connections within Census. We extend our existing POST and PATCH /destinations endpoints to allow you to pass the tokens and OAuth client information so that Census can communicate with the destination APIs on your behalf.

Changes to the Management API

POST /destinations and PATCH /destinations/{id}

To create a new customer-managed OAuth destination connection, we require that you use our standard Create a Destination endpoint with the following credentials payloads.

We outline examples for Salesforce, LinkedIn, Hubspot, GoogleAds, and Facebook Ads below. If you need to create other OAuth destinations via API, please reach out to us at support.getcensus.com .

Request body credentials

Salesforce

additional properties description type
connection.credentials.username the username of the authenticating user string
connection.credentials.instance_url the instance url of the authenticating user, ie https://e6a0000022abc2def-dev-ed.lightning.force.com string
connection.credentials.domain must be one of login.salesforce.com or test.salesforce.com (for sandbox accounts) string
connection.credentials.client_id Census will use this to communicate with salesforce APIs on your behalf string
connection.credentials.jwt_signing_key Census will use this to communicate with salesforce APIs on your behalf string

Linkedin

additional properties description type
connection.credentials.access_token the access token you received at the end of the OAuth authorization flow after you exchanged the code for an access_token string
connection.credentials.refresh_token the refresh token that will be used to exchange for a new access token when the access token expires. Optional as some destinations don’t support refresh tokens string
connection.credentials.client_id Census will use this refresh the access token string
connection.credentials.client_secret Census will use this to refresh the access_token string
connection.credentials.access_token_expires_in This allows us to proactively and gracefully refresh the access token before contacting the service. Required if refresh_token provided number (seconds until the access token expires)
connection.credentials.account_id The Linkedin Ad account ID to use with this connection number
connection.credentials.account_name The Linkedin Ad account name to use with this connection string

Hubspot

additional properties description type
connection.credentials.access_token the access token you received at the end of the OAuth authorization flow after you exchanged the code for an access_token string
connection.credentials.refresh_token the refresh token that will be used to exchange for a new access token when the access token expires. Optional as some destinations don’t support refresh tokens string
connection.credentials.client_id Census will use this refresh the access token string
connection.credentials.client_secret Census will use this to refresh the access_token string
connection.credentials.access_token_expires_in This allows us to proactively and gracefully refresh the access token before contacting the service. Required if refresh_token provided number (seconds until the access token expires)