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.
Post-Auth Redirects
You may redirect your users after they finish connecting an account by adding the next query param to your auth URL. Your redirect may include a path and query params, and should be encoded.
For example, to redirect to this URL:
https://example.com/friends?species=fox&name=carlYou would use the following:
?next=https%3A%2F%2Fexample.com%2Ffriends%3Fspecies%3Dfox%26name%3DcarlYou must add all redirect domains and subdomains (e.g. apple.com and account.apple.com must both be added if used) to the Redirect Domains field under User Auth on the developer settings page. Wildcards are not supported. So for the above example, you would add example.com.
Any non-whitelisted domains added to the next param will cause the account connection to fail.
Auth URL Example
https://behold.link/YOUR_AUTH_ID?type=bp&customId=INTERNAL_ID&next=https%3A%2F%2Fexample.comIn 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. After authorization is complete, they will be redirected to https://example.com.
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:
