Link a social login identity to a user profile

Link a social login identity provider
Open Recipe

Links a new social identity to an existing user account. Once linked, the new identity can be used to sign in to that account. To make this call, you must have a valid social login token received after a user authenticates through the social provider account to be linked; you also need a valid Registration access token for the user record to be updated.

Note that you can only merge accounts if the social login provider returns a verified email address as part of its API response.

Authentication

No authentication is required to call this operation.

Base URL

The base URL for this operation is your Identity Cloud Capture domain; for example:

https://educationcenter.us- dev.janraincapture.com

Your Capture domain (also known as a Registration domain) can be found in Console on the Manage Application page:

Examples

Example: Link New Social Identity

This command links an existing user account (identified by the access token issued to the user) to a social login account (identified by the token parameter).

curl -X POST \
  --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
  --data-urlencode 'flow=standard' \
  --data-urlencode 'flow_version=20190618143040022299' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'redirect_uri=http://localhost' \
  --data-urlencode 'token=b5f21ac796fc5f2d76027a8b8c28366df1b8623c' \
  --data-urlencode 'access_token=z0y98xv76u5t4rs3' \
  https://my-app.janraincapture.com/oauth/link_account_native

📘

Your API call must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.

ParameterTypeRequiredDescription
access_tokenstringRegistration access token returned after authentication or registration with a previous call (/oauth/auth_native, /oauth/auth_native_traditional, and so on) if the response_type parameter was set to token. If the response_type was set to code, you must exchange the authorization code for an access token using the /oauth/token call.
client_idstringAPI client ID used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured by using the Configuration API.
flowstringName of the flow configured with the login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in JavaScript SDK- based implementations.

The default flow provisioned with Registration applications is named the standard flow; if you have multiple flows, you can find a list of valid flow names using the Configuration API.

You can omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.
flow_versionintegerVersion number of the flow set in the** flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in JavaScript SDK-based implementations; however, this call won't accept a version of HEAD. Instead, you must specify the version number if you want to use the most recent version.

You can find a list of versions for your flow using the Configuration API. This parameter can be omitted if you you configure the flow version in the
default_flow_version** setting for the API client used to make this call.
localestringCode for the language you want to use for the profile management experience. This parameter determines the language for any error messages returned to you and corresponds to the janrain.settings.language JavaScript setting used in JavaScript SDK-based implementations. The default locale provisioned with the standard Registration flow is en-US; other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.
redirect_uristringRequired for legacy purposes and not used for any functionality in this call. It must begin with http: or https:, and we recommend that this match the URL and protocol of your website.

This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in JavaScript SDK-based implementations.
tokenstringOne-time token used for social authentication. This is the token passed from the social login application to your token URL. The token must be received from the same Social Login application that is configured for the API client used to make this call; this can be configured in the Default Settings for your Registration application if you have a single Social Login application.

The token is a unique 40-character string and can be used with the auth_info endpoint to retrieve a user's social profile directly; however, this is not necessary when using the oauth endpoints for registration because that data is retrieved and stored for you.

Responses

200 OK

Successful Response

A successful call returns the following response:

{
  "stat": "ok"
}

Error - Invalid Social Login Token

The example error response below indicates that the social login token passed into the call is invalid or expired.

{
  "stat": "error",
  "code": 400,
  "error_description": "Unexpected HTTP status code from server: 400",
  "error": "engage_error",
  "request_id": "utwvg3ydh9etv2bv"
}

Error - Invalid Registration Access Token

The example error response below indicates that the Registration access token passed into the call is invalid or expired.

{
    "stat": "error",
    "code": 413,
    "error_description": "invalid access token",
    "error": "invalid_access_token",
    "request_id": "9xmecweny6bxt5n2"
}

Error - Social Account Already Used

The example error response below indicates that the social identity the user has attempted to link is already associated with an account and can't be linked.

{
  "stat": "error",
  "code": 361,
  "error_description": "that account already exists",
  "error": "unique_violation",
  "request_id": "bqpucbv8x4dxwtsn",
  "message": "That account is already in use."
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call wasn't included. The error message describes which parameter is missing.

{
  "stat": "error",
  "code": 100,
  "error_description": "missing arguments: flow",
  "error": "missing_argument",
  "request_id": "uyeem84bmqmnjuu4"
}

Error - Invalid Flow Value

The example error response below indicates that the value provided for one or more of the flow, flow_version, or locale parameters is invalid. Flow versions are unique across environments, so check that the version value included in the call is for the correct environment (that is, your development or production application).

{
  "stat": "error",
  "code": 500,
  "error_description": "could not find a flow named 'standard' with version '12345abc-1234-abcd-1234-12345abcde12' and locale 'en-US'",
  "error": "unexpected_error"
  "request_id": "murynd7fhpysq6um"
}

Error - Invalid API Client Permissions

The example error response below indicates that the API client used to make the call is not configured with the login_client feature.

{
  "stat": "error",
  "code": 403,
  "error_description": "This client does not support log in and registration.",
  "error": "permission_error",
  "request_id": "y3sthb9dey6mv65e"
}