swagger: "2.0" info: version: 1.0.0 title: Gateway Social Auth schemes: - https host: qa-gateway-social-auth.theorchard.io paths: /hello/: get: summary: Check the health of the application. responses: 200: description: 200 OK examples: application/json: { "status": "ok" } /auth/facebook: get: summary: Get the facebook authentication window description: Getting this route will open up a authentication window to facebook wher the user can enter credentials parameters: - in: query name: state required: true type: string description: The parameter to control the redirection to original application. The state variables i facebook api represents a way to transfer information from client to the callback function for further processing. We use the state variables to pass 7 variables to the callback function without which the functionality of the authentication is broken. The state variables are comma-separated string which are base64 encoded. The following are the variables which appear in the state in the specific order - 1. REDIRECT_URL - to go back to the application on succcessful completion of authentication process 2. PARTICIPANT_ID - the id of the participant to store for audit logging 3. APPLICATION_NAME - The name of the application where the request is coming from 4. ORCHARD_IDENTITY_ID - The id of the user who initiated the auth process 5. ORCHARD_PROFILE_ID - The profile id of the user who is trying to authenticate a artist 6. ORCHARD_PROFILE_TYPE - The profile type of the user who is trying to authenticate a artist 7. SPOTIFY_ID - The spotify id of the participant to verify with Laylo responses: '302': description: Redirects to facebook authentication page at 'https://facebook.com/v8.0' '400': description: Bad request. State parameter must be present and be in valid form. '500': description: Internal server error due to misconfigured environment variables /auth/facebook/callback: get: summary: The callback url which is called when authentication from facebook succeeds or fails description: This url is set with Facebook Login application created with Facebook developer account. The authentication is complete when the user successfully enters his credentials with facebook and either authorizes The Orchard application to access its data or denies the request. In either case, parameters are passed to callback url for further processing. On receiving this request, the process to o obtain a long lived access token from instagram is initiated. On completion of which the token is sent to Laylo for fetching content. Laylo will do further validation for matching the user handle. If everything is successful, we are redirected to the url in state. parameters: - in: query name: state required: true type: string description: The parameter to control the redirection to original application. The state variables in facebook api represents a way to transfer information from client to the callback function for further processing. We use the state variables to pass 7 variables to the callback function without which the functionality of the authentication is broken. The state variables are comma-separated string which are base64 encoded. The following are the variables which appear in the state in the specific order - 1. REDIRECT_URL - to go back to the application on succcessful completion of authentication process 2. PARTICIPANT_ID - the id of the participant to store for audit logging 3. APPLICATION_NAME - The name of the application where the request is coming from 4. ORCHARD_IDENTITY_ID - The id of the user who initiated the auth process 5. ORCHARD_PROFILE_ID - The profile id of the user who is trying to authenticate a artist 6. ORCHARD_PROFILE_TYPE - The profile type of the user who is trying to authenticate a artist 7. SPOTIFY_ID - The spotify id of the participant to verify with Laylo - in: query name: code type: string description: The code obtained on successful authenticaiton from instagram. This code can be used to obtain a token. This is the start of Proof Key Code Exchange protocol - in: query name: error type: string description: This query param is passed if the instagram api encounters error on authentication. Example of the error includes, when user denies authorization to OrchardGo application. - in: query name: error_reason type: string description: This query param is passed when a error is present. This indicates why the error occured. - in: query name: error_description type: string description: This query param is passed when a error is present. This includes a detailed description of the error responses: '302': description: Redirects to the url in state with status indicating whether the authentication and other processing were successful or not. If successful, the instagram parameters are passed in the request as query params. If not successful, errors are passed in the request as query params. '403': description: When referrer is not from instagram the request is not authorized to pass through. '400': description: When validation of the request fails when state is missing or the query params are malformed. '500': description: When something unexpected goes wrong most probably due to instagram api error or incorrect environment confi /deauth/facebook/callback: post: summary: The callback url which is invoked when the user explicitly removes application from facebook through Business Integration tab on their settings page. description: This is the callback which is invoked when the user goes into application in instagram and explicitly removes the application. This is a way for facebook to tell us that user has deauthorized your 3rd party application which means we need to invalidate the access tokens. On receiving this request, the access token with Laylo will be instructed to be deleted. For doing that we retrieve the spotifyId related to the facebook user id from dynamodb table and send a request to Laylo to unlink the participant. parameters: - in: body name: signed request description: The signed request body received from facebook which contains user id. The signed request is encrypted with the client secret of the facebook application. The signed request is in the form of .. On decrypting, the signed request we obtain the facebook user id for which the application is to be deauthorized. required: true schema: type: object properties: signed_request: type: string responses: '200': description: When the access token for the user has been successfully deleted '400': description: When the signed request is malformed or incorrect. /delete/facebook/callback: post: summary: The callback url which is invoked when the user explicitly removes application from instagram. description: This is the callback which is invoked when the user requests facebook to delete its data from 3rd party application. The mechanics of the request are similar to deauthorization but we have to return a url where the user can check their data deletion status and confirmation code. parameters: - in: body name: signed request description: The signed request body received from facebook which contains user id. The signed request is encrypted with the client secret of the facebook application. The signed request is in the form of .. On decrypting, the signed request we obtain the facebook user id for which the application is to be deauthorized. required: true schema: type: object properties: signed_request: type: string responses: '200': description: When the data for the user has been successfully deleted schema: type: object properties: url: type: string description: The url where the user can check the data deletion status. confirmation_code: type: string description: The confirmation code for the data deletion request. '400': description: When the signed request is malformed or incorrect.