Building Authenticated Apps

If you want to build an app that allows the users to authenticate with an external system and perform actions in that system via your app, you can create an Authenticated App. Users will be able to authenticate with the external system via your app directly from Blink.

To work properly, your app must provide two publicly accessible endpoints that Blink can call:

The Authentication Process

This section describes how your app should implement the POST /auth/<auth_id> endpoint

The user opens the manage apps page and clicks your app.

The user clicks the blue connect button.

This click triggers an HTTP request that Blink proxys to the proxy url you have specified for your app. Your app code therefore needs a handler for POST /auth/<auth_id> where auth_id is the Auth ID shown on the management page for your app in the Blink Admin panel. The request will come through with all headers described in the Proxy Endpoint documentation.

Your app code should construct an authorization URL to return to Blink. Blink will open this URL in a new window. This URL should be some page where a user can authenticate with the external service so that your app can capture their credentials.

Your app's POST /auth/<auth_id> endpoint should then return the Authorization URL to Blink in the following JSON object.

{  
   "code":"OK",
   "message":"OK",
   "data":{  
      "authorization_url":"https://your-external-service.site/login"
   }
}

Blink will open this URL in a new window so that the user can authenticate with the external service.

Your code for handling this authentication should save a Linked Account for the user with the Add User Linked Account endpoint.

Linked accounts contain a number of fields, the only one that MUST be saved for each linked account is external_account_id. This should be some unique identifier for the user's account in the external system the user can use to identify the account on the apps management page.

Removing Accounts

This section describes how your app should implement the DELETE /linked-accounts/<linked_account_id> endpoint

When a user wishes to disconnect their account in your external service from Blink they click the Disconnect button on the account page in the apps management panel:

When this button is pressed, Blink proxys a call to DELETE /linked-accounts/<linked_account_id> to the proxy_url for your app.

When receiving a call to this endpoint, your app should delete the linked account from Blink by calling the Delete User Linked Account endpoint. Your app can then perform any arbitrary actions to de-authenticate the user from the service, e.g revoking tokens.