Complete social login

Login a user by using social login
Open Recipe
Merge a social login account
Open Recipe

Completes a social login. To make this call, you must have a valid social login token received after a user successfully authenticates by using one of the identity providers you've enabled for your social login application. See Configure social login by using the Social Login Dashboard for more information on how to get social login tokens.

📘

Your API call must be a POST request with all parameters included in the body of the request. These parameters can't be passed as URL parameters.

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 1: Complete Social Authentication

This command uses the social login token 8cff5948c5476ba61b8b4b635cc84664bcd2d57d to complete a social login.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "12345abcde12345abcde12345abcde12",
    "flow": "standard",
    "flow_version": "20190618143040022299",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "registration_form": "socialRegistrationForm",
    "token": "8cff5948c5476ba61b8b4b635cc84664bcd2d57d"
  }' 
  https://my-app.janraincapture.com/oauth/auth_native

If the user doesn't exist in the Identity Cloud Registration database, the error response includes profile information from the IDP that can be used to register the user via a call to oauth/register_native. Only data defined in the form specified in the registration_form member will be returned in this error response.

Example 2: Merge Social Accounts

This command merges a new social login account with an existing user account. The existing account is referenced by the token parameter, and is the social login token assigned when the user logged on with that account. The new social login account is identified by the merge_token parameter, and is the social login token assigned when the user logged on by using the new account.

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 'response_type=token' \
  --data-urlencode 'token=12ab34cd56ef78gh90ij12kl34mn56op78qr90st' \
  --data-urlencode 'merge_token=ab12cd34ef56gh78ij90kl12mn34op56qr78st78' \
  https://my-app.janraincapture.com/oauth/auth_native

Parameters

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

ParameterTypeRequiredDescription
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 for the login experience . 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 will not 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 social login 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 flow is en-US; other locales must be configured in your flow before they can be referenced.

You can find a list of valid locales for your flow using the Configuration API.
merge_tokenstringIf you have had a previous call fail with the error code 380 email_address_in_use error, you can merge the new social account into the existing one by including the merge_token parameter in this call or the auth_native_traditional call authenticating the user's existing account. The token value for this parameter must be the same token from the previous failed auth_native call.
redirect_uristringRequired for legacy purposes and is not used for any functionality in this call. The parameter value 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.
registration_formstringName of the form used for social registration. This parameter determines what's included in the error response if no existing record can be found that uses the same email address as the one returned by the social provider after a successful authentication.

When set, the response will include values for prereg_fields, which includes data from the social provider's payload mapped to fields in your social registration form. You can use this data to pre-populate the parameters for the oauth/register_native.

The default form name for social registration configured for the standard flow is socialRegistrationForm. You can find a list of valid forms and associated fields for your flow using the Configuration API.

This form name corresponds to the name of the JTL tag used for the social registration form in JavaScript SDK-based implementations.
response_typestringDetermines whether you receive an access token, an authorization code, or both after a user is successfully registered or authenticated; if omitted, the response type defaults to token.

This parameter corresponds to the janrain.settings.capture.responseType JavaScript setting used in JavaScript SDK-based implementations.

Allowed values are:

• code
• token
• code_with_token
thin_registrationbooleanDetermines the behavior of the auth_native call if no existing record is found that uses the same email address as the one returned by the social provider after a successful authentication.

If true, this endpoint creates a new record, and social data is stored in the profiles section of the user record. The standard flow provisioned with Registration applications is also configured to copy social data, if available, to the top-level schema attributes for email, displayName, givenName, and familyName upon record creation.

If set to false or omitted from the call, you will need to complete two-step registration using oauth/register_native. See the registration_form parameter for information on gathering data from the social provider response for use in the social registration form.
tokenstringOne-time token used for social authentication. This is the token passed from the social login application to your token URL. It must be received from the same social login application tconfigured for the API client used to make this call; this may be configured in the default settings for your Registration application if you have a single social login application.

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

Responses

200 OK

Successful Response

A successful response returns the user profile in the capture_user object along with an access_token or authorization_code depending on the response_type parameter set in the call. Note that is_new will reflect true if the user did not previously exist and you have thin_registration set to true.

{
  "capture_user": {
    "created": "2016-04-20 17:02:18.649505 +0000",
    "uuid": "67890def-6789-defg-6789-67890defgh67",
    // additional profile data...
  },
  "is_new": false,
  "stat": "ok",
  "access_token": "z0y98xv76u5t4rs3"
}

Error - User Not Yet Registered

The example error response below indicates that neither the user's social identity nor the email address returned by the provider are currently registered. You may proceed to register the user with the oauth/register_native call using the same social login token passed into the previous call. If your call included the registration_form parameter, the error response will include prereg_fields with data from the social provider's payload mapped to fields in your social registration form. Note that this error may still be encountered when thin_registration is set to true if the chosen social provider doesn't return an email address.

{
  "stat": "error",
  "code": 310,
  "error_description": "no such user",
  "error": "record_not_found",
  "request_id": "d9yrm9g7vfrh7bk3",
  "prereg_fields": {
    "firstName": "John",
    "middleName": null,
    "lastName": "Doe",
    "emailAddress": "johndoe@example.com",
    "displayName": "JohnDoe",
    "mobile": null,
    "optInRegistration": false,
    "gender": "",
    "birthdate": null,
    "phone": null,
    "addressStreetAddress1": null,
    "addressStreetAddress2": null,
    "addressCity": null,
    "addressPostalCode": null,
    "addressState": "",
    "addressCountry": ""
  }
}

Error - Email Address Already Registered

The example error response below indicates that the user's social identity is not currently registered but the email address returned by the provider matches an existing record. You may proceed to ask the user to authenticate through the existing account and then merge in the new social account by using the first social login token for the merge_token parameter in the next call. If the response indicates that the existing provider is capture, use the oauth/auth_native_traditional call; otherwise use auth_native again after getting a social login token for the existing account, which will be passed in the token parameter.

{
  "stat": "error",
  "code": 380,
  "error_description": "a user already exists with that email address",
  "error": "email_address_in_use",
  "request_id": "x4jdsa9mbajg7hsj",
  "existing_provider": "googleplus",
  "existing_display_name": "janedoe",
  "existing_photo": {
    "id": 10628,
    "value": "https://lh3.googleusercontent.com/fyd7jkgbnjLBX/AAAAAAAAAAI/AAAAAAAAAAA/hjsGTSDljl/photo.jpg?sz=400",
    "type": "other"
  },
  "existing_date_created": "2016-04-21 23:13:58.437196 +0000"
}

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": 200,
  "error_description": "invalid token",
  "error": "invalid_argument",
  "request_id": "zygzvaatua8ezk2v"
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not 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 isn't 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"
}