We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

Social User Login

Step 1. The user logs in to social, a social code is generated.

1.1 As the user clicks the social login button on your site, you need to call https://id.piano.io/id/api/v1/publisher/login/social (hereinafter "/social") to redirect the user to the social provider.

1.2 After the user's successful login to their social account, the social provider assigns an identifier (social code) for this login which is passed to Identity Management backend.

1.3 Identity Management saves the social code and generates a response_id to be used for further interaction with your system.

1.4 The logic of /social concludes with redirecting the user (with some response_id added to the URL) to your webpage (redirect_uri defined in the endpoint input parameters).

Step 2. Identity Management database is updated (if necessary), an access token is returned.

2.1 Having called /social, you need to make a request to https://id.piano.io/id/api/v1/publisher/login/social/code (hereinafter "social/code") with a certain response_id in it. Identity Management returns an access token and/or the Identity Management user data to be considered for further authentication. The response model is as follows:

  • access_token (String): The user's access token if the status is OK and no further action is required.

  • status (String): Status of the user accounts linkage. The possible values are:

    • OK: Accounts are linked, consents are given.

    • ERROR: Some error occurred

    • CONFIRM: There is no Identity Management user linked to the social account in the response_id; the client now needs to call publisher/login/social/codeConfirm (see below).

    • ADDITIONAL_INPUT: The user still hasn't given some mandatory consents on the client's site. The client now needs to call /login/social/codeAdditional (see below).

  • linking_state (String): A unique identifier of this authentication session.

  • social_type (String): The social provider name.

  • email (String): The user's email

  • first_name (String): The user's first name

  • last_name (String): The user's last name

  • password_confirmation_available (Boolean): If true, a matching user with email/password already exists in the Piano database but is not yet linked to this social account.

  • linked_social_accounts (Array of String): This user already has some accounts with other social providers.

  • redirect_uri (String): The site to redirect the user.

2.2. You may need to take extra actions depending on the status value you got on Step 2.1.

If your user has neither a confirmed account nor checked consents, you don't need to call both endpoints, social/codeAdditional will suffice.

Please note that the URL of your social/codeConfirm request is formed with account of social/code (Step 2.1) response values.

a) If social/code has returned status = confirm and password_confirmation_available = true, your request to social/codeConfirm should include:

  • aid

  • api_token

  • linking_state

  • email

  • password

Use case: Linking a social user to an existing Identity Management user with email/password.

b) If social/code has returned status = confirm and some non-empty linked_social_accounts, your request to social/codeConfirm should include:

  • aid

  • api_token

  • linking_state

  • confirmed_token

Use case: Linking a social user to an existing social user recorded in Identity Management database.

Last updated: