The Social Sign In POST request connects a new or existing Collinson SmartLink consumer with an account on a remote social service (e.g. facebook) and allows for authentication via the remote social service. The response to a successful request includes an OAuth2 Bearer Token that can be used to access Consumer-API routes on behalf of the consumer.
The request body is a JSON string defining a SocialConnection object. The values of this object must be obtained from the remote social service before calling the Social Sign In route.
Example request:
{ "socialConnection" : { "accessToken" : "AAABcrBWa7VIBAAOkZBmdTAtyDiCfNusHS4h1BCpZBEt", "displayName" : null, "expireTime" : 1330386127579, "imageUrl" : "http%3A%2F%2Fgraph.facebook.com%2F100003361197548%2Fpicture", "password" : null, "profileUrl" : "http%3A%2F%2Ffacebook.com%2Fprofile.php%3Fid%3D100003361197548", "providerId" : "facebook", "providerUserId" : "100003361197548", "refreshToken" : null, "secret" : null}}Social Connection fields
|
Name |
Type |
Required |
Description |
|
|
String |
Y |
Email address used by the consumer in the remote service. This is used as the Consumer's primary email in the Collinson SmartLink platform if the request results in a new Collinson SmartLink Consumer. |
|
password |
String |
N |
Password associated with the Email if the email already exists in the Collinson SmartLink platform. Required when adding a new Social Connection to an existing Collinson SmartLink Consumer. |
|
providerId |
String |
Y |
Identifier of the remote service, e.g. 'facebook'. |
|
providerUserId |
String |
Y |
Identifier of the Consumer in the remote service. |
|
displayName |
String |
N |
A display name for the connection. |
|
profileUrl |
String |
N |
A link to the remote service's user profile page. |
|
imageUrl |
String |
N |
An image visualizing the connection. |
|
accessToken |
String |
Y |
The access token required to make authorized API calls to the remote service. |
|
secret |
String |
N |
The secret token needed to make authorized API calls. Required for OAuth1-based connections. |
|
refreshToken |
String |
N |
An optional token used to renew the connection. Always null for OAuth1-based connections. |
|
expireTime |
Long Integer |
N |
The time the connection expires. Optional. Always null for OAuth1-based connections. |
Example requests:
curl -v -H "Content-Type: application/json" -H "Accept: application/json" -H "api: [current_api_version]" -H "Authorization: Bearer b5d69eb6-b9ee-4ee4-852c-1dff379af4ed" -X POST -d '{"socialConnection":{"accessToken":"AAABcrBWa7VIBAAOkZBmdTAtyDiCfNusHS4h1BCpZBEt","displayName":null,"email":"[email protected]","expireTime":1330386127579,"imageUrl":"http%3A%2F%2Fgraph.facebook.com%2F100003361197548%2Fpicture","password":null,"profileUrl":"http%3A%2F%2Ffacebook.com%2Fprofile.php%3Fid%3D100003361197548","providerId":"facebook","providerUserId":"100003361197548","refreshToken":null,"secret":null}}' https://int.mylinkables.com/consumerapi/social/signincurl -v -H "Content-Type: application/json" -H "Accept: application/xml" -H "api: [current_api_version]" -H "Authorization: Bearer b5d69eb6-b9ee-4ee4-852c-1dff379af4ed" -X POST -d '{"socialConnection":{"accessToken":"AAABcrBWa7VIBAAOkZBmdTAtyDiCfNusHS4h1BCpZBEt","displayName":null,"email":"[email protected]","expireTime":1330386127579,"imageUrl":"http%3A%2F%2Fgraph.facebook.com%2F100003361197548%2Fpicture","password":null,"profileUrl":"http%3A%2F%2Ffacebook.com%2Fprofile.php%3Fid%3D100003361197548","providerId":"facebook","providerUserId":"100003361197548","refreshToken":null,"secret":null}}' https://int.mylinkables.com/consumerapi/social/signinThere are three paths that can be taken through the Social Sign In route.
The request specifies the SocialConnection providerId and providerUserId values of a connection already stored in the Collinson SmartLink platform. In this case the Collinson SmartLink record is updated to match the provided SocialConnection, as the connection data (access token, etc) may have been updated in the remote service. A consumer-api bearer token is returned in the response and the response status code is SUCCESS (100).
The request specifies a SocialConnection containing an email not yet registered in the Collinson SmartLink platform. In this case a new Collinson SmartLink consumer is created having that email and is linked to a new SocialConnection record. The email is automatically recorded as verified. A consumer-api bearer token is returned in the response and the response status code is SUCCESS (100).
The request specifies a SocialConnection containing a SocialConnection email already registered in the Collinson SmartLink platform, but the SocialConnection itself does not yet exist. In this case the Collinson SmartLink password corresponding to the email is required to link the SocialConnection to the existing Collinson SmartLink Consumer.
If the password is not supplied the response status code is PASSWORD_REQUIRED (432). Please collect the password from the user and try again.
If the supplied password does not match the password for the email address the response status code is NOT_FOUND (404). Please collect a corrected password from the user and try again.
If the supplied password is the correct password the SocialConnection record is created, a consumer-api bearer token is returned in the response, and the response status code is SUCCESS (100).
If the Accept type is set to json the following will be returned:
{ "bearerToken":"1_b61f0c75-649a-423b-9dfd-e044fc816a5c", "statusCode":100, "statusDescription":"Success"}If the Accept type is set to xml the following will be returned:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><socialSignInPostResponse xmlns="http://www.linkablenetworks.com/consumerapi" bearerToken="1_b61f0c75-649a-423b-9dfd-e044fc816a5c" statusDescription="Success" statusCode="100"/>