Auth URL
Every Behold account has a unique auth URL. Whenever anyone visits this URL they will be directed through an Instagram OAuth flow. They will be asked to grant access to their Instagram, and once they agree, a new source will be added to your account. They do not need a Behold account to complete this process.
You can find your auth URL by clicking the “Add source” button in the Behold dashboard.
By default your auth link will create a basic source. To authorize an advanced source instead, add either type=bp or type=fb as query params to the auth URL to connect via business portfolio or Facebook account respectively.
Custom Source IDs
You may add a custom identifier to sources by appending a customId param to your auth URL. The custom ID will be associated with any source connected using this URL, and will be returned in subsequent webhooks and API responses via the customId attribute. This is useful for associating sources with users in your system. Custom IDs may be up to 64 characters long and must contain only numbers, letters, underscores and hyphens.
customId is an immutable attribute. It is set the first time a source is connected, and then cannot be changed except by deleting the source and reconnecting it.
Auth URL Example
https://behold.link/YOUR_AUTH_ID?type=bp&customId=INTERNAL_IDIn this example, users will be directed to authorize access to one or more Instagram accounts via Facebook Business Portfolio (because of the type=bp). When this is done, a source will be created in your account with the customId attribute set to INTERNAL_ID.
Token Invalidation
The access token associated with a source can be invalidated for a number of reasons (e.g. Instagram password change). We refer to this as a source being “disconnected.” If that happens, the source needs to be reconnected by having the account owner visit your auth link and follow the same procedure as when the source was originally connected.
Feeds associated with a disconnected source will continue to function, but won’t update as new posts are published.
We recommend listening for invalidated tokens by using webhooks.
Branding
On the developer settings page of the Behold dashboard you can upload an app icon and input a name for your company or app. This will be displayed alongside the Behold logo during the auth process. The uploaded logo should be an icon that fits well into a circle.
If you activate the Show auth interstitial switch, users will be shown a screen like this before authorizing:
