loading

Identity Cloud: Social Login API v2

Configure and maintain social logins, social sharing, and the social login process.

Learn more:


Overview

The Social Login API helps you to configure and maintain social logins, social sharing, and the social login process. The Social API consists of the endpoints detailed below.

The Social Login endpoints

These endpoints focus on the mechanics of the login process including authentication, application settings, identity providers, and social profile data:

  • /add_or_update_access_token
  • /auth_info
  • /get_app_settings
  • /get_available_providers
  • /get_contacts
  • /get_user_data
  • /providers
  • /set_app_settings
  • /set_auth_providers

The Social Sharing endpoints

These endpoints focus on social sharing tasks, including getting or setting an application’s sharing providers, returning the number of a times a given URL has been shared, and distributing shared content with a provider or with specified recipients on a provider’s network:

  • /get_share_count
  • /get_share_providers
  • /set_share_providers
  • /sharing/broadcast
  • /sharing/direct

The App Whitelist endpoints

These endpoints query and change domains for an application’s whitelist. The whitelist determines which domains can be used for registering and logging in users:

  • /add_domain_patterns
  • /get_domain_patterns
  • /set_domain_patterns

The Backplane Server endpoints

These endpoints query and configure the Backplane server (used to communicate with all of the Backplane-enabled apps on a page):

  • /get_backplane_properties
  • /set_backplane_properties

Note that Backplane is no longer available as part of the Akamai Identity Cloud. Existing instances of Backplane will continue to be supported, but no new instances of Backplane can be deployed.

The Account Mapping endpoints

These endpoints query and change social login account mappings, the associations between a conventional user account and a user’s social identities:

  • /map
  • /unmap

Accessing the Social Login endpoints

The Social Login API endpoints can be accessed using this syntax:

https://{domain}/api/v2/{endpoint}

To access your API endpoints, replace {domain} with the name of your social application domain and replace {endpoint} with the name of the API endpoint you want to use. For example:

https://akamai-documentation.rpxnow.com/api/v2/get_available_providers

API Authentication

As a general rule, no authentication is required in order to call the Social APIs. Instead, your API calls must include the apiKey parameter. In addition, the apiKey parameter must be set to your social login API key. You can find the value of your API key on the Settings page in the Social Login Dashboard: look for the field labeled API Key (Secret).

However, there are two exceptions to the no-authentication-required rule. The /providers endpoint, for one, does not require any authentication (e.g., a token, or a usernames and password) nor does it require the apiKey parameter. Instead, all you have to do is call the endpoint. For example, anyone can access the following endpoint without including authentication and without adding any parameters:

https://greg-stemp.rpxnow.com/api/v2/providers

Similarly, the /signin/oauth_token endpoint does not require authentication or the apiKey parameter. However, your call to that endpoint must include a token returned from a social login provider. (In some cases, such as Twitter, you must also include the token secret.) When a user logs on to an identity provider, part of their logon success response will include an IFDP token. For example:

"accessToken": "EAAGc5PYTqaMBAGWpz1pMG6Of4Ol8I2"

That token (e.g., EAAGc5PYTqaMBAGWpz1pMG6Of4Ol8I2) must be included in your /signin/oauth_token API call.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Add domain patterns POST /api/v2/add_domain_patterns{?apiKey,domains}
Add or update access token POST /api/v2/add_or_update_access_token{?identifier,token,apiKey}
Authentication information POST /api/v2/auth_info{?token,apiKey,extended,tokenUrl}
Get application settings POST /api/v2/get_application_settings{?apiKey}
Get available properties POST /api/v2/get_available_providers{?callback}
Get backplane properties POST /api/v2/get_backplane_properties{?apiKey}
Get contacts POST /api/v2/get_contacts{?identifier,apiKey,contactType,existingUser,providerFields}
Get domain patterns POST /api/v2/get_domain_patterns{?apiKey,domains}
Get share count POST /api/v2/get_share_count{?apiKey,provider,callback,url}
Get share providers POST /api/v2/get_share_providers{?call}
Associate a primary key with a social identity POST /api/v2/map{?identifier,apiKey,overwrite,primaryKey}
Get social login providers POST /api/v2/providers
Set application settings POST /api/v2/set_app_settings{?apiKey,domainRedirect,favicon,googleProfileUrl,oneTimeUseTokens,postToTokenUrl,privacyPolicy}
Set authentication providers POST /api/v2/set_auth_providers{?providers,apiKey,deviceType}
Set backplane properties POST /api/v2/set_backplane_properties{?bus,server,apiKey,password,remove,username,version}
Set domain patterns POST /api/v2/set_domain_patterns{?apiKey,domains}
Set share providers POST /api/v2/set_share_providers{?share,apiKey,email,format}
Share activity information with a provider POST /api/v2/sharing_broadcast{?identifier,objectId,image,media,message,source,title,actionLink,description,url,shortenUrl,deviceToken}
Share activity information with specific people POST /api/v2/sharing_direct{?recipients,apiKey,identifier,recipientUrls,image,media,message,source,title,actionLink,description,url,shortenUrl,deviceToken}
Exchange a social login provider token POST /api/v2/signin/oauth_token{?token,provider,tokenSecret}
Remove an identity provider from a primary key POST /api/v2/unmap{?identifier,primaryKey,apiKey,all_identifiers,unlink}

Add domain patterns

Appends domains to the current whitelist for an application.

POST /api/v2/add_domain_patterns{?apiKey,domains}

Sample: /api/v2/add_domain_patterns?apiKey=1234567891234567891234567891234567891234&domains=documentation.akamai.com%2Ceducation.akamai.com

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
domains String documentation.akamai.com,education.akamai.com Comma-separated list of domains that will be used as the website whitelist.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode domains='localhost, somewhere.com, *.examples.com'\
    https://documentation.akamai.rpxnow.com/api/v2/add_domain_patterns

Add or update access token

Adds or updates an OAuth access token for a user outside the usual login flow. When a user logs in with an OAuth1 or OAuth2 Identity Provider, the Akamai Identity Cloud requests an OAuth token from the provider. This OAuth token is used when making subsequent API calls to the provider. The add_or_update_access_token call adds a token retrieved using a different method to the Identity Cloud.

POST /api/v2/add_or_update_access_token{?identifier,token,apiKey}

Sample: /api/v2/add_or_update_access_token?identifier=http%3A//www.facebook.com/profile.php%3Fid%3D123456789123456789123&token=123456789123456789&apiKey=1234567891234567891234567891234567891234

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
identifier String http://www.facebook.com/profile.php?id=123456789123456789123 Identifier associated with the social login identity provider. This value must be formatted as part of a URL.
token String 123456789123456789 Access token for the user. Tokens must be requested from identity providers based on their API requirements.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode token=123456789123456789\
    --data-urlencode identifier=http://www.facebook.com/profile.php?id=123456789123456789123\
    https://documentation.akamai.rpxnow.com/api/v2/add_or_update_access_token

Authentication information

This call is used to authenticate Social Login users. You must use https to make this call. During the authentication process, the auth_info call is used to retrieve the profile information of the user. Using the apiKey of the application, and the one time token provided by Social Login, it returns the requested data from the Identity Provider.

POST /api/v2/auth_info{?token,apiKey,extended,tokenUrl}

Sample: /api/v2/auth_info?token=a1b2c3d4e5f6g7h8i9j0&apiKey=1234567891234567891234567891234567891234&extended=false&tokenUrl=https%3A//example.com/token_url

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
token String a1b2c3d4e5f6g7h8i9j0 Social Login auth_info token.
Optional query parameters
extended Boolean false When true, returns the extended Simple Registration and HCard data in addition to the normalized Portable Contacts format. The default value is false.
tokenUrl String https://example.com/token_url Validates the specified token URL value against the URL that was originally sent.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "profile": {
        "verifiedEmail": "sam@example.com",
        "googleUserId": "123456789123456789123",
        "displayName": "sam",
        "preferredUsername": "sam",
        "url": "https://www.google.com/profiles/123456789123456789123",
        "providerName": "Google",
        "identifier": "https://www.google.com/profiles/123456789123456789123",
        "email": "sam@example.com",
        "name": {
            "givenName": "Sam",
            "familyName": "Knot",
            "formatted": "Sam Knot"
        }
    },
    "accessCredentials": {
        "scopes": "Blogger,Google Buzz,Google Contacts,YouTube,Picasa Web Albums,Google Calendar,Google Docs",
        "oauthToken": "1/1234567891234567891234567891234567891234567",
        "type": "OAuth",
        "oauthTokenSecret": "123456789123456789123456"
    },
    "merged_poco": {
        "preferredUsername": "Sam",
        "languagesSpoken": [
            "en"
        ],
        "name": {
            "formatted": "Sam Knot",
            "familyName": "Knot",
            "givenName": "Sam"
        },
        "urls": [
            {
                "type": "other",
                "value": "https://www.google.com/profiles/123456789123456789123"
            }
        ],
        "emails": [
            {
                "type": "other",
                "value": "sam@example.com"
            }
        ]
    }
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode token=a1b2c3d4e5f6g7h8i9j0\
    --data-urlencode extended=false\
    --data-urlencode tokenUrl=https://example.com/token_url \
    https://documentation.akamais.rpxnow.com/api/v2/auth_info

Get application settings

Enables you to make API calls to return social login application settings such as the domain redirect and privacy policy URLs.

POST /api/v2/get_application_settings{?apiKey}

Sample: /api/v2/get_application_settings?apiKey=1234567891234567891234567891234567891234

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "privacyPolicy": null,
    "favicon": null,
    "domainRedirect": null,
    "postToTokenUrl": true,
    "oneTimeUseTokens": true,
    "googleProfileUrl": true
}

Sample curl request

curl-X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    https://documentation.akamai.rpxnow.com/api/v2/get_application_settings

Get available properties

Returns a list of configured providers for an application. The providers call is similar, but only returns providers configured for an application. This call is used if you are using custom code for Social Login instead of using the Akamai Identity Cloud JavaScript implementation.

POST /api/v2/get_available_providers{?callback}

Sample: /api/v2/get_available_providers?callback=callback

Parameter Type Sample Description
Optional query parameters
callback String callback When present, data is returned using the JSONP (JSON with Padding) format.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "signin": [
        "aol",
        "blogger",
        "facebook",
        "flickr",
        "google",
        "hyves",
        "livejournal",
        "myopenid",
        "netlog",
        "openid",
        "verisign",
        "wordpress",
        "yahoo"
    ],
    "social": [
        "facebook",
        "yahoo"
    ],
    "share": [
        "facebook",
        "yahoo"
    ]
}

Sample curl request

curl -X POST \
    https://documentation.akamai.com/api/v2/get_available_providers

Get backplane properties

Use this call for Backplane Protocol-enabled Identity Cloud solutions only. The get_backplane_properties call queries the Backplane server to verify that Backplane credentials have been set up. If the proper credentials are in place, details are returned. If not, no details are returned.

POST /api/v2/get_backplane_properties{?apiKey}

Sample: /api/v2/get_backplane_properties?apiKey=1234567891234567891234567891234567891234

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "backplane_servers": []
}

Sample curl request

curl-X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
     https://documentation.akamai.rpxnow.com/api/v2/get_backplane_properties

Get contacts

The get_contacts call uses the apiKey and identifier to return a list of all the contacts related to the user. The data returned and the type of relationship differs between Identity Providers. Before using get_contacts you must enable contacts for the Identity Provider in the Social Login Dashboard.

POST /api/v2/get_contacts{?identifier,apiKey,contactType,existingUser,providerFields}

Sample: /api/v2/get_contacts?identifier=0987098709870987&apiKey=1234567891234567891234567891234567891234&contactType=friends&existingUser=true&providerFields=firstName%2CmiddleName%2ClastName

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
identifier String 0987098709870987 Identifier returned from the auth_info API call.
Optional query parameters
contactType Enumeration friends Specify friends to return identifiers for every friend of the user. If you do not specify a value, friends will be returned if available. Twitter does not support the friends contactType. Instead specify followers, following, or friendships. Note that VK supports followers and following, but not friendships. No other providers support any of these values, and will return an error.
existingUser Boolean true When set to true, returns a value that identifies whether a user has previously authenticated with the Akamai Identity Cloud application.
providerFields String firstName,middleName,lastName Comma-separated list of provider-specific profile fields to return the associated data. This option is supported by Facebook, LinkedIn, Mixi, Salesforce, VK, and Xing, and is ignored if used with other providers. Note that no validation is performed. If you specify an incorrect field name then an error is likely to occur. Check the provider’s documentation for valid profile fields.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "response": {
        "startIndex": 1,
        "itemsPerPage": 5,
        "totalResults": 5,
        "entry": [
            {
                "displayName": "Bob Johnson",
                "emails": [
                    {
                        "type": "other",
                        "value": "bob@example.com"
                    }
                ]
            },
            {
                "displayName": "Cindy Smith",
                "emails": [
                    {
                        "type": "other",
                        "value": "cindy.smith@example.com"
                    }
                ]
            },
            {
                "displayName": "Fred Williams",
                "emails": [
                    {
                        "type": "other",
                        "value": "fred.williams@example.com"
                    }
                ]
            },
            {
                "emails": [
                    {
                        "type": "other",
                        "value": "j.lewis@example.com"
                    }
                ]
            },
            {
                "displayName": "Mary Jones",
                "emails": [
                    {
                        "type": "other",
                        "value": "mary.jones@example.com"
                    }
                ]
            },
            {
                "displayName": "Patricia Green",
                "emails": [
                    {
                        "type": "other",
                        "value": "p.green@example.com"
                    }
                ]
            }
        ]
    }
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode identifier=0987098709870987 \
    --data-urlencode contactType=friends \
    https://documentation.akamai.rpxnow.com/api/v2/get_contacts

Get domain patterns

Use this call to return a list of all domains currently whitelisted for an application.

POST /api/v2/get_domain_patterns{?apiKey,domains}

Sample: /api/v2/get_domain_patterns?apiKey=1234567891234567891234567891234567891234&domains=documentation.akamai.com%2Ceducation.akamai.com

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
domains String documentation.akamai.com,education.akamai.com Comma-separated list of domains that will be used as the website whitelist.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "domains": [
        "localhost",
        "somewhere.com",
        "*.example.com"
    ]
}

Sample curl request

curl-X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    https://documentation.akamai.rpxnow.com/api/v2/get_domain_patterns

Get share count

Returns the number of a times a given URL has been shared.

POST /api/v2/get_share_count{?apiKey,provider,callback,url}

Sample: /api/v2/get_share_count?apiKey=1234567891234567891234567891234567891234&provider=facebook&callback=callback&url=http%3A//example.com/pinboard

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
Optional query parameters
callback String callback When present, data is returned using the JSONP (JSON with Padding) format.
provider String facebook Identity provider. When present, the API call returns a share count for the specified provider.
url String http://example.com/pinboard URL of the content being shared.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "share_count": 113
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode url=http://example.com/pinboard\
    https://documentation.akamai.rpxnow.com/api/v2/get_share_count

Get share providers

It returns a list of email and sharing providers configured for the application. This call has no required parameters. It identifies the proper application by the realm prefacing the URL path. This API call works only with the current Sharing solution.

POST /api/v2/get_share_providers{?call}

Sample: /api/v2/get_share_providers?call=call

Parameter Type Sample Description
Optional query parameters
call String call When present, data is returned using the JSONP (JSON with Padding) format.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "email": [
        "google",
        "yahoo"
    ],
    "share": [
        "email",
        "linkedin"
    ]
}

Sample curl request

curl -X POST \
    https://documentation.akamai.rpxnow.com/api/v2/get_share_providers

Associate a primary key with a social identity

Use the map to associate a primary key with a user’s social identity. The mapping API lets sites store each of the user’s external identifiers along with the primary key of the site’s user/account record on the server. They are then included on every call to auth_info where the social identifier has been previously mapped.

POST /api/v2/map{?identifier,apiKey,overwrite,primaryKey}

Sample: /api/v2/map?identifier=0987098709870987&apiKey=1234567891234567891234567891234567891234&overwrite=false&primaryKey=12

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
identifier String 0987098709870987 Identifier returned from the auth_info API call.
Optional query parameters
overwrite Boolean false When set to false, mappings are created only if the specified identifier does not already have a mapping. The default value is true.
primaryKey String 12 Primary key found in the user profile.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode identifier=0987098709870987 \
    --data-urlencode primaryKey=12\
    https://documentation.akamai.rpxnow.com/api/v2/map

Get social login providers

This call returns a list of configured sign-in or social providers configured for an application.

POST /api/v2/providers

Status 200 application/json

Response body:

{
    "stat": "ok",
    "signin": [
        "aol",
        "facebook",
        "foursquare",
        "google",
        "linkedin",
        "live_id",
        "mixi",
        "openid",
        "orkut",
        "paypal",
        "salesforce",
        "sinaweibo",
        "twitter",
        "yahoo"
    ],
    "social": [
        "facebook",
        "linkedin",
        "myspace",
        "twitter"
    ],
    "shareWidget": {
        "share": [
            "email",
            "facebook",
            "linkedin",
            "myspace",
            "twitter",
            "yahoo"
        ],
        "email": [
            "google",
            "yahoo"
        ]
    }
}

Sample curl request

curl -X POST \
    https://documentation.akamai.rpxnow.com/api/v2/providers

Set application settings

Enables you to make API calls to configure social login application settings such as the domain redirect and privacy policy URLs.

POST /api/v2/set_app_settings{?apiKey,domainRedirect,favicon,googleProfileUrl,oneTimeUseTokens,postToTokenUrl,privacyPolicy}

Sample: /api/v2/set_app_settings?apiKey=1234567891234567891234567891234567891234&domainRedirect=documentation.akamai.com%2Ceducation.akamai.com&favicon=https%3A//documentation.akamaki.rpxnow.com/favicon.ico&googleProfileUrl=true&oneTimeUseTokens=true&postToTokenUrl=true&privacyPolicy=https%3A//documentation.akamaki.rpxnow.com/privacy

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
Optional query parameters
domainRedirect String documentation.akamai.com,education.akamai.com URL where users are who access your sign-in URL redirected.
favicon String https://documentation.akamaki.rpxnow.com/favicon.ico URL of your favicon. Favicons are icons that appear on web browser tabs, in a browser’s address bar, and next to browser bookmarks.
googleProfileUrl Boolean true When set to true, Google Profile URls are returned instead of OpenID Connect URLs. The default value is false.
oneTimeUseTokens Boolean true When set to true, tokens can only be used once before they expire.
postToTokenUrl Boolean true When set to true, uses the POST method to submit authentication tokens to your token endpoint.
privacyPolicy String https://documentation.akamaki.rpxnow.com/privacy URL to the location of your privacy policy.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode privacyPolicy=https://janrain-docs.rpxnow.com/privacy\
    --data-urlencode favicon=http://janrain-docs.rpxnow.com/favicon.ico \
    --data-urlencode googleProfileUrl=true\
    https://documentation.akamai.rpxnow.com/api/v2/get_application_settings

Set authentication providers

Use set_auth_providers to define the list of identity providers provided by the server to sign-in enabled pages. This is the same list that is managed by the dashboard.

POST /api/v2/set_auth_providers{?providers,apiKey,deviceType}

Sample: /api/v2/set_auth_providers?providers=%5B%22facebook%22%2C%22yahoo%22%5D&apiKey=1234567891234567891234567891234567891234&deviceType=android

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
providers String ["facebook","yahoo"] A comma-separated string of provider specifiers.
Optional query parameters
deviceType Enumeration android Without a parameter value, set_auth_providers affects the provider list for the web version of the Social Login UI. Allowed parameter values are web (changes the providers presented to normal web traffic); iphone (changes the providers presented to web traffic identified as originating from an iPhone); android (changes the providers presented to web traffic identified as originating from an android based mobile device).

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode providers='["facebook","yahoo"]'\
    https://documentation.akamai.rpxnow.com/api/v2/set_auth_providers

Set backplane properties

The set_backplane_properties call configures the Backplane server used to communicate with all of the Backplane-enabled apps on a page.

POST /api/v2/set_backplane_properties{?bus,server,apiKey,password,remove,username,version}

Sample: /api/v2/set_backplane_properties?bus=example_bus&server=documentation.akamai.com&apiKey=1234567891234567891234567891234567891234&password=p%40ssw0rd&remove=true&username=backplane-admin&version=v1.1

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
bus String example_bus Backplane bus name.
server String documentation.akamai.com Domain name for the Backplane server.
Optional query parameters
password String p@ssw0rd Password portion of the Backplane credentials. This parameter is required if you do not include the remove parameter.
remove Boolean true When set to true, removes the Backplane configuration for the specified server or bus. When false, creates a new Backplane configuration.
username String backplane-admin Username portion of the Backplane credentials. This parameter is required if you do not include the remove parameter.
version String v1.1 Backplane server version. The default value is v1.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode server=example.com \
    --data-urlencode bus=example_bus \
    --data-urlencode username=larrydrebes \
    --data-urlencode password=rosebud \
    https://documentation.akamai.rpxnow.com/api/v2/set_backplane_properties

Set domain patterns

Use the set_domain_patterns call to replace the current whitelist for an application.

POST /api/v2/set_domain_patterns{?apiKey,domains}

Sample: /api/v2/set_domain_patterns?apiKey=1234567891234567891234567891234567891234&domains=documentation.akamai.com%2Ceducation.akamai.com

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
domains String documentation.akamai.com,education.akamai.com Comma-separated list of domains that will be used as the website whitelist.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234 \
    --data-urlencode domains='["localhost", "somewhere.com", "*.example.com"]' \
    https://documentation.akamai.rpxnow.com/api/v2/set_domain_patterns

Set share providers

Use set_share_providers to define the providers offered by Social Sharing. You can set both sharing and email providers.

POST /api/v2/set_share_providers{?share,apiKey,email,format}

Sample: /api/v2/set_share_providers?share=email%2Clinkedin&apiKey=1234567891234567891234567891234567891234&email=smnp&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
share String email,linkedin Sharing provider options. If no values are supplied the UI will not have any sharing provider options.
Optional query parameters
email String smnp Email provider options. If no values are supplied the UI will not have any email provider options.
format Enumeration xml The format to use in the response, either json or xml. The default is json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode share='email, linkedin'\
    https://documentation.akamai/api/v2/set_share_providers

Share activity information with a provider

The broadcast call shares activity information directly with a provider. The information provided in the parameters is passed along to a provider to publish on their network. The broadcast call shares with one provider at a time, determined by the identifier or device token that you use.

POST /api/v2/sharing_broadcast{?identifier,objectId,image,media,message,source,title,actionLink,description,url,shortenUrl,deviceToken}

Sample: /api/v2/sharing_broadcast?identifier=https%3A//documentation.akamai.com/users/bob&objectId=39151712878215225&image=http%3A//documentation.akamai.com/sites.default/themes/logo.png&media=http%3A//documentation.akamai.com/sites.default/social-login.mp4&message=This%20video%20explains%20how%20social%20login%20works%20in%20the%20Akamai%20Identity%20Cloud.&source=http%3A//documentation.akamai.com&title=Social%20Login&actionLink=%7B%22name%22%3A%20%22Example%22%2C%20%22link%22%3A%20%22http%3A//www.example.com%22%7D&description=Social%20Login%20instructional%20video.&url=http%3A//example.com/pinboard&shortenUrl=true&deviceToken=https%3A//documentation.akamai.com/users/bob

Parameter Type Sample Description
Optional query parameters
actionLink String {"name": "Example", "link": "http://www.example.com"} Link that appears beneath user-generated message and content fields. In the case of Facebook, this link appears next to the Like and Comment links.
description String Social Login instructional video. Description of the shared content. The description appears in the preview of the shared object and explains what is being shared.
deviceToken String https://documentation.akamai.com/users/bob Identifier URL or device token of the user sharing an activity. Do not use the device token with mobile browsers.
identifier String https://documentation.akamai.com/users/bob Identifier URL or device token of the user sharing an activity. Do not use the device token with mobile browsers.
image String http://documentation.akamai.com/sites.default/themes/logo.png Image associated with the content being shared.
media String http://documentation.akamai.com/sites.default/social-login.mp4 Flash or video object associated with the content being shared.
message String This video explains how social login works in the Akamai Identity Cloud. Message associated with the activity being shared.
objectId String 39151712878215225 Facebook-only. Use this parameter to share to a Facebook fan page instead of the User’s wall. The value is the Object ID assigned to the fan page. See the Facebook developer documentation for more information on the Object ID.
shortenUrl Boolean true When false, disables the Identity Cloud URL shortening service. When true, activates URL shortening.
source String http://documentation.akamai.com URL of the site sharing the activity.
title String Social Login Title given to the shared content.
url String http://example.com/pinboard URL of the content being shared.

Status 200 application/json

Response body:

{
    "provider": "facebook",
    "mode": "broadcast",
    "success": true,
    "results": [
        {
            "success": true,
            "recipientId": "me",
            "shareResultUrl": "http://wwww.facebook.com/100002302927767/posts/939384179481671",
            "messageId": "100002302927767_939384179481671",
            "share": {
                "message": "Hey come look at this amazing thing!",
                "title": "Share this!",
                "url": "http://rpx.me/QlU9l",
                "description": "Fractal image.",
                "image": "http://www.coolmath.com/fractals/images/fractal11.gif",
                "media": "",
                "actionName": "",
                "objectName": "",
                "objectId": ""
            }
        }
    ]
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode identifier=0987098709870987 \
    --data-urlencode message='Testing one two three'\
    --data-urlencode title='My title'\
    --data-urlencode url=http://test.com \
    --data-urlencode image=http://documentation.akamai.com/sites.default/themes/akamai/logo.png \
    --data-urlencode actionLink='{"name": "Example", "link": "http://www.example.com"}'\
    https://documentation.akamai.rpxnow.com/api/v2/sharing/broadcast

Share activity information with specific people

This API shares activity information directly with the specified recipients on a provider’s network, instead of publishing it to everyone on the network. The direct call shares with one provider at a time, determined by the identifier or device token you enter.

POST /api/v2/sharing_direct{?recipients,apiKey,identifier,recipientUrls,image,media,message,source,title,actionLink,description,url,shortenUrl,deviceToken}

Sample: /api/v2/sharing_direct?recipients=%5B%22http%3A//twitter.com/account/profileuser_id%3Dcgfe75313%22%5D&apiKey=1234567891234567891234567891234567891234&identifier=https%3A//documentation.akamai.com/users/bob&recipientUrls=%7B%22http%3A//myidentifier.com%22%3A%20%22http%3A//documentation.akamai.com%22%7D&image=http%3A//documentation.akamai.com/sites.default/themes/logo.png&media=http%3A//documentation.akamai.com/sites.default/social-login.mp4&message=This%20video%20explains%20how%20social%20login%20works%20in%20the%20Akamai%20Identity%20Cloud.&source=http%3A//documentation.akamai.com&title=Social%20Login&actionLink=%7B%22name%22%3A%20%22Example%22%2C%20%22link%22%3A%20%22http%3A//www.example.com%22%7D&description=Social%20Login%20instructional%20video.&url=http%3A//example.com/pinboard&shortenUrl=true&deviceToken=https%3A//documentation.akamai.com/users/bob

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
recipients String ["http://twitter.com/account/profileuser_id=cgfe75313"] JSON-formatted list of identifiers associated with the recipients being contacted.
Optional query parameters
actionLink String {"name": "Example", "link": "http://www.example.com"} Link that appears beneath user-generated message and content fields. In the case of Facebook, this link appears next to the Like and Comment links.
description String Social Login instructional video. Description of the shared content. The description appears in the preview of the shared object and explains what is being shared.
deviceToken String https://documentation.akamai.com/users/bob Identifier URL or device token of the user sharing an activity. Do not use the device token with mobile browsers.
identifier String https://documentation.akamai.com/users/bob Identifier URL or device token of the user sharing an activity. Do not use the device token with mobile browsers.
image String http://documentation.akamai.com/sites.default/themes/logo.png Image associated with the content being shared.
media String http://documentation.akamai.com/sites.default/social-login.mp4 Flash or video object associated with the content being shared.
message String This video explains how social login works in the Akamai Identity Cloud. Message associated with the activity being shared.
recipientUrls String {"http://myidentifier.com": "http://documentation.akamai.com"} Enables sharing multiple URLs to multiple recipients. The parameter value must be a JSON object of recipients and shared URLs. Recipients not appearing in this object use the value defined in the URL parameter to share.
shortenUrl Boolean true When false, disables the Identity Cloud URL shortening service. When true, activates URL shortening.
source String http://documentation.akamai.com URL of the site sharing the activity.
title String Social Login Title given to the shared content.
url String http://example.com/pinboard URL of the content being shared.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "response": {
        "provider": "twitter",
        "mode": "direct",
        "success": true,
        "recipientIds": [
            "123456789"
        ],
        "results": [
            {
                "success": true,
                "recipientId": "123456789",
                "messageId": "123456789123456789",
                "share": {
                    "message": "Testing one two three."
                }
            }
        ]
    }
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode identifier=0987098709870987 \
    --data-urlencode recipients='["http://twitter.com/account/profileuser_id=blah75313"]'\
    --data-urlencode message='Testing one two three'\
    --data-urlencode title='My title'\
    --data-urlencode url=http://rpxme.com/test\
    https://documentation.akamai.rpxnow.com/api/v2/sharing/direct

Exchange a social login provider token

This endpoint exchanges a Social Identity Provider OAuth token, or an IDP token for an Akamai Social Login token, which will be needed for social registration and login calls using the Identity Cloud’s OAuth endpoints. This endpoint is used if you are implementing a solution that authenticates users with an Identity Provider directly and not using an Identity Cloud Social Login application.

POST /api/v2/signin/oauth_token{?token,provider,tokenSecret}

Sample: /api/v2/signin/oauth_token?token=EAAV6lsQIR0gBAItAtDeUZBbsFiHuGt45dTdg&provider=facebook&tokenSecret=R6WsN9OciOmVME8Z7yuSAC2MXiXxGS1B1w5AxuxoSqvKi

Content-Type: application/json

Request body:

{
    "stat": "ok",
    "token": "e96213b7bfddd1884b91544a11b5d5be52316590"
}
Parameter Type Sample Description
Required query parameters
provider Enumeration facebook Social identity provider. Allowed values are facebook, twitter, or googleplus. Note that, despite the name, the provider parameter does not reference any Google+ endpoints or scopes. The Akamai Identity Cloud no longer supports Google+. Instead, all Google social logins are made through Google Sign-In. The name googleplus has been retained for backwards compatibility.
token String EAAV6lsQIR0gBAItAtDeUZBbsFiHuGt45dTdg IDP token from Facebook or Twitter.
Optional query parameters
tokenSecret String R6WsN9OciOmVME8Z7yuSAC2MXiXxGS1B1w5AxuxoSqvKi Required when using Twitter as the social login identity provider.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "token": "e96213b7bfddd1884b91544a11b5d5be52316590"
}

Remove an identity provider from a primary key

Unmapping removes an Identity Provider from a primary key as well as allowing you to optionally unlink your application from the user’s account with the provider.

POST /api/v2/unmap{?identifier,primaryKey,apiKey,all_identifiers,unlink}

Sample: /api/v2/unmap?identifier=0987098709870987&primaryKey=12&apiKey=1234567891234567891234567891234567891234&all_identifiers=true&unlink=true

Parameter Type Sample Description
Required query parameters
apiKey String 1234567891234567891234567891234567891234 Social Login API key. This key can be found on the Social Login Dashboard.
identifier String 0987098709870987 Identifier currently mapped to the primaryKey.
primaryKey String 12 Primary key found in the users table.
Optional query parameters
all_identifiers Boolean true When true, all identifiers mapped to the primaryKey are removed. The default value is false.
unlink Boolean true Unlinks your application from the user’s social login provider.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=1234567891234567891234567891234567891234\
    --data-urlencode identifier=0987098709870987 \
    --data-urlencode all_identifiers=true\
    --data-urlencode primaryKey=12\
    --data-urlencode unlink=true\
    https://documentation.akamai.rpxnow.com/api/v2/unmap

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

Authentication

Retrieves user profile information during social login.

Download schema: authentication_information.json

Sample POST response:

{
    "stat": "ok",
    "profile": {
        "verifiedEmail": "sam@example.com",
        "googleUserId": "123456789123456789123",
        "displayName": "sam",
        "preferredUsername": "sam",
        "url": "https://www.google.com/profiles/123456789123456789123",
        "providerName": "Google",
        "identifier": "https://www.google.com/profiles/123456789123456789123",
        "email": "sam@example.com",
        "name": {
            "givenName": "Sam",
            "familyName": "Knot",
            "formatted": "Sam Knot"
        }
    },
    "accessCredentials": {
        "scopes": "Blogger,Google Buzz,Google Contacts,YouTube,Picasa Web Albums,Google Calendar,Google Docs",
        "oauthToken": "1/1234567891234567891234567891234567891234567",
        "type": "OAuth",
        "oauthTokenSecret": "123456789123456789123456"
    },
    "merged_poco": {
        "preferredUsername": "Sam",
        "languagesSpoken": [
            "en"
        ],
        "name": {
            "formatted": "Sam Knot",
            "familyName": "Knot",
            "givenName": "Sam"
        },
        "urls": [
            {
                "type": "other",
                "value": "https://www.google.com/profiles/123456789123456789123"
            }
        ],
        "emails": [
            {
                "type": "other",
                "value": "sam@example.com"
            }
        ]
    }
}

Authentication members

Member Type Description
Authentication: Retrieves user profile information during social login.
accessCredentials Authentication.accessCredentials Authentication information returned from the social identity provider.
merged_poco Authentication.merged_poco User’s Portable Contacts object.
profile Authentication.profile Attributes retrieved from the user profile.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.
Authentication.accessCredentials: Authentication information returned from the social identity provider.
oauthToken String OAuth access token issued by the social identity provider.
oauthTokenSecret String Secret associated with the OOAuth token.
scopes String Scopes associated with the user.
type String Type of token issued by the social login identity provider.
Authentication.merged_poco: User’s Portable Contacts object.
emails Authentication.merged_poco.emails[] Individual email account information.
languagesSpoken Array ISO language code for the spoken language.
name Authentication.merged_poco.name Name information for the user.
preferredUsername String User’s preferred name, the user’s nickname or the name that the user prefers to be known by.
urls Authentication.merged_poco.urls[] Individual URL associated with the user.
Authentication.merged_poco.emails[]: Individual email account information.
type String Type of email account.
value String Email address.
Authentication.merged_poco.name: Name information for the user.
familyName String User’s last name.
formatted String User’s full name.
givenName String User’s first name.
Authentication.merged_poco.urls[]: Individual URL associated with the user.
type String Type of URL.
value String URL.
Authentication.profile: Attributes retrieved from the user profile.
displayName String User’s display name.
email String User’s email address.
googleUserId String User’s unique Google identifier.
identifier String URL identifier.
name Authentication.profile.name User name information.
preferredUsername String User’s preferred name, the user’s nickname or the name that the user prefers to be known by.
providerName String Name of the user’s social identity provider.
url String URL to the user’s online social identity profile.
verifiedEmail String User’s email address.
Authentication.profile.name: User name information.
familyName String User’s last name.
formatted String User’s full name.
givenName String User’s first name.

ApplicationSettings

Returns application property values for an application.

Download schema: get_application_settings.json

Sample POST response:

{
    "stat": "ok",
    "privacyPolicy": null,
    "favicon": null,
    "domainRedirect": null,
    "postToTokenUrl": true,
    "oneTimeUseTokens": true,
    "googleProfileUrl": true
}

ApplicationSettings members

Member Type Description
ApplicationSettings: Returns application property values for an application.
domainRedirect String, Null Available for enterprise level apps and apps owned by Akamai’s Identity Cloud partners. A URL redirect destination for users visiting your sign-in URL (such as http://akamai-docs.rpxnow.com).
favicon String, Null URL of your favicon, which can be displayed by some identity providers during authentication.
googleProfileUrl Boolean When true, returns a user’s globally unique Google profile URLs as the identifier element in the auth_info API call response instead of the OpenID URL.
oneTimeUseTokens Boolean When true, tokens for the auth_info API call can be used only once.
postToTokenUrl Boolean When true, uses the HTTP POST method to submit auth_info tokens to your token URL.
privacyPolicy String, Null URL sent with requests for registration data and displayed by the identity provider as a link to the user.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

AvailableProperties

Returns the identity providers who have been configured for traditional login and registration, social login and registration, and social sharing.

Download schema: get_available_providers.json

Sample POST response:

{
    "stat": "ok",
    "signin": [
        "aol",
        "blogger",
        "facebook",
        "flickr",
        "google",
        "hyves",
        "livejournal",
        "myopenid",
        "netlog",
        "openid",
        "verisign",
        "wordpress",
        "yahoo"
    ],
    "social": [
        "facebook",
        "yahoo"
    ],
    "share": [
        "facebook",
        "yahoo"
    ]
}

AvailableProperties members

Member Type Description
AvailableProperties: Returns the identity providers who have been configured for traditional login and registration, social login and registration, and social sharing.
share Array Lists all the identity providers that have been configured for social sharing.
signin Array Lists all the identity providers that have been configured for traditional login and registration.
social Array Lists all the identity providers that have been configured for social login and registration.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

BackplaneProperties

Open-source protocol used by Enterprises and small businesses to integrate with other web applications. Backplane is no longer available for use with the Akamai Identity Cloud. However, existing backplane implementations are still supported.

Download schema: get_backplane_properties.json

Sample POST response:

{
    "stat": "ok",
    "backplane_servers": []
}

BackplaneProperties members

Member Type Description
BackplaneProperties: Open-source protocol used by Enterprises and small businesses to integrate with other web applications. Backplane is no longer available for use with the Akamai Identity Cloud. However, existing backplane implementations are still supported.
backplane_servers Array Array specifying the domain names of the backplane servers.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

Contacts

Returns information about the social media contacts associated with the specified user.

Download schema: get_contacts.json

Sample POST response:

{
    "stat": "ok",
    "response": {
        "startIndex": 1,
        "itemsPerPage": 5,
        "totalResults": 5,
        "entry": [
            {
                "displayName": "Bob Johnson",
                "emails": [
                    {
                        "type": "other",
                        "value": "bob@example.com"
                    }
                ]
            },
            {
                "displayName": "Cindy Smith",
                "emails": [
                    {
                        "type": "other",
                        "value": "cindy.smith@example.com"
                    }
                ]
            },
            {
                "displayName": "Fred Williams",
                "emails": [
                    {
                        "type": "other",
                        "value": "fred.williams@example.com"
                    }
                ]
            },
            {
                "emails": [
                    {
                        "type": "other",
                        "value": "j.lewis@example.com"
                    }
                ]
            },
            {
                "displayName": "Mary Jones",
                "emails": [
                    {
                        "type": "other",
                        "value": "mary.jones@example.com"
                    }
                ]
            },
            {
                "displayName": "Patricia Green",
                "emails": [
                    {
                        "type": "other",
                        "value": "p.green@example.com"
                    }
                ]
            }
        ]
    }
}

Contacts members

Member Type Description
Contacts: Returns information about the social media contacts associated with the specified user.
response Contacts.response JSON object containing information about the contacts associated with a user.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.
Contacts.response: JSON object containing information about the contacts associated with a user.
entry Contacts.response.entry[] JSON-formatted array containing information about an individual contact.
itemsPerPage Integer Specifies the number of contacts returned per API call.
startIndex Integer Specifies the starting point for returning contacts. For example, 1 means to start with the first contact in the collection while 7 means to start with the seventh contact in the collection.
totalResults Integer Specifies the total number of contacts associated with the user.
Contacts.response.entry[]: JSON-formatted array containing information about an individual contact.
displayName String Display name of the contact.
emails Contacts.response.entry[].emails[] Array containing the email addresses associated with the contact.
Contacts.response.entry[].emails[]: Array containing the email addresses associated with the contact.
type String Specifies the type of email address used by the contact.
value String Contact’s email address.

DomainPatterns

Returns information about the domain included on an application’s social login whitelist. For security reasons, only whitelisted domains are allowed to communicate with your Social Login application. That means that these are the only domains that can host your registration UI.

Download schema: get_domain_patterns.json

Sample POST response:

{
    "stat": "ok",
    "domains": [
        "localhost",
        "somewhere.com",
        "*.example.com"
    ]
}

DomainPatterns members

Member Type Description
DomainPatterns: Returns information about the domain included on an application’s social login whitelist. For security reasons, only whitelisted domains are allowed to communicate with your Social Login application. That means that these are the only domains that can host your registration UI.
domains Array Array containing the names of the domains on the application’s domains whitelist.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

ShareCount

Returns the number of times that a URL has been shared.

Download schema: get_share_count.json

Sample POST response:

{
    "stat": "ok",
    "share_count": 113
}

ShareCount members

Member Type Description
ShareCount: Returns the number of times that a URL has been shared.
share_count Integer Number of times that the specified URL has been shared.
stat Enumeration Indicates the status of the given operation, either ok, error, or fail.

ShareProviders

Returns a list of all the email and sharing providers configured for an application.

Download schema: get_share_providers.json

Sample POST response:

{
    "stat": "ok",
    "email": [
        "google",
        "yahoo"
    ],
    "share": [
        "email",
        "linkedin"
    ]
}

ShareProviders members

Member Type Description
ShareProviders: Returns a list of all the email and sharing providers configured for an application.
email Array Email providers configured for an application.
share Array Social sharing providers configured for an application.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.

Providers

Returns a list of configured sign-in or social providers configured for an application.

Download schema: providers.json

Sample POST response:

{
    "stat": "ok",
    "signin": [
        "aol",
        "facebook",
        "foursquare",
        "google",
        "linkedin",
        "live_id",
        "mixi",
        "openid",
        "orkut",
        "paypal",
        "salesforce",
        "sinaweibo",
        "twitter",
        "yahoo"
    ],
    "social": [
        "facebook",
        "linkedin",
        "myspace",
        "twitter"
    ],
    "shareWidget": {
        "share": [
            "email",
            "facebook",
            "linkedin",
            "myspace",
            "twitter",
            "yahoo"
        ],
        "email": [
            "google",
            "yahoo"
        ]
    }
}

Providers members

Member Type Description
Providers: Returns a list of configured sign-in or social providers configured for an application.
shareWidget Providers.shareWidget JSON-formatted object containing information about the sharing providers configured for an application.
signin Array Traditional login and registration providers configured for an application.
social Array Social login and registration providers configured for an application.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.
Providers.shareWidget: JSON-formatted object containing information about the sharing providers configured for an application.
email Array Email providers configured for an application.
share Array Social sharing providers configured for an application.

SharingBroadcast

Shares activity information directly with a provider. The information provided in the parameters is passed along to a provider to publish on their network.

Download schema: sharing_broadcast.json

Sample POST response:

{
    "provider": "facebook",
    "mode": "broadcast",
    "success": true,
    "results": [
        {
            "success": true,
            "recipientId": "me",
            "shareResultUrl": "http://wwww.facebook.com/100002302927767/posts/939384179481671",
            "messageId": "100002302927767_939384179481671",
            "share": {
                "message": "Hey come look at this amazing thing!",
                "title": "Share this!",
                "url": "http://rpx.me/QlU9l",
                "description": "Fractal image.",
                "image": "http://www.coolmath.com/fractals/images/fractal11.gif",
                "media": "",
                "actionName": "",
                "objectName": "",
                "objectId": ""
            }
        }
    ]
}

SharingBroadcast members

Member Type Description
SharingBroadcast: Shares activity information directly with a provider. The information provided in the parameters is passed along to a provider to publish on their network.
mode Enumeration Type of sharing activity, either direct or broadcast.
provider String Identifier for the social media provider.
results SharingBroadcast.results[] JSON-formatted array of information returned after the content has been shared.
success Boolean Indicates whether the broadcast call succeeded.
SharingBroadcast.results[]: JSON-formatted array of information returned after the content has been shared.
messageId String Unique identifier associated with the broadcast message.
recipientId String Unique identifier of the share recipient.
share SharingBroadcast.results[].share JSON-formatted object containing information about the content being shared.
shareResultUrl String URL of the shared item.
success Boolean Indicates whether the broadcast call succeeded.
SharingBroadcast.results[].share: JSON-formatted object containing information about the content being shared.
actionName String Action name.
description String Brief description of the shared content.
image String URL of the image associated with the shared content.
media String Flash or video object associated with the content being shared.
message String Message associated with the shared content.
objectId String Facebook-only. Use this parameter to share to a Facebook fan page instead of the User’s wall. The value is the Object ID assigned to the fan page.
objectName String Name of the shared content.
title String Title of the shared content.
url String URL of the content being shared.

SharingDirect

Shares activity information directly with the specified recipients on a provider’s network, instead of publishing it to everyone on the network.

Download schema: sharing_direct.json

Sample POST response:

{
    "stat": "ok",
    "response": {
        "provider": "twitter",
        "mode": "direct",
        "success": true,
        "recipientIds": [
            "123456789"
        ],
        "results": [
            {
                "success": true,
                "recipientId": "123456789",
                "messageId": "123456789123456789",
                "share": {
                    "message": "Testing one two three."
                }
            }
        ]
    }
}

SharingDirect members

Member Type Description
SharingDirect: Shares activity information directly with the specified recipients on a provider’s network, instead of publishing it to everyone on the network.
response SharingDirect.response Information regarding the shared content.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.
SharingDirect.response: Information regarding the shared content.
mode Enumeration Indicates whether the content was shared with selected users (direct) or published to everyone on the social network (broadcast).
provider String Unique identifier of the social media provider where the content was shared.
recipientIds Array JSON-formatted array of identifiers associated with the recipients who were contacted.
results SharingDirect.response.results[] Information about the recipients who should have received the shared content.
success Boolean If true, indicates that the content was successfully shared.
SharingDirect.response.results[]: Information about the recipients who should have received the shared content.
messageId String Unique identifier of the message that was shared.
recipientId String Unique identifier of the recipient.
share SharingDirect.response.results[].share Information about the shared message.
success Boolean If true, indicates that the recipient received the content.
SharingDirect.response.results[].share: Information about the shared message.
message String Text of the shared message.

OAuthToken

Exchanges a social identity provider’s IDP token for an Akamai Identity Cloud social login token. The social login token is required for social registration and login calls that use the Identity Cloud OAuth endpoints. This endpoint is used if you are implementing a solution that directly authenticates users with an identity provider.

Download schema: signin_oauth_token_req.json

Sample POST request:

{
    "provider": "facebook",
    "token": "EAAV6lsQIR0gBAItAtDeUZBbsFiHuTxhLaHLw9TqGDsXK6GQodDfgKXcCkxkZCZBxLKsxsWgV0iZATVAzx2RGlsOIFDIals3ZCblCEJn25pTj4Lk7XZCCEweKkHfHZBPP8B75dXc1BagGjNy8ZBpyObZB8FZCWSK0AAWevv15aEh85lTwZZDD"
}

OAuthToken members

Member Type Description
OAuthToken: Exchanges a social identity provider’s IDP token for an Akamai Identity Cloud social login token. The social login token is required for social registration and login calls that use the Identity Cloud OAuth endpoints. This endpoint is used if you are implementing a solution that directly authenticates users with an identity provider.
provider String Identifier for the social login provider.
token String Authentication token returned from the social login identify provider. This token must be exchanged for an Akamai Identity Cloud social login token.

Errors

This section provides details on the error responses generated by the Social API.

Error responses

Social API errors are returned as JSON objects similar to the following:

{
    "stat": "fail",
    "err": {
        "code": 1,
        "msg": "Invalid parameter: partnerKey"
    }
}

Each error response includes an error code. However, error codes are sometime shared by multiple events. For example, error code 3 can refer to any of the following errors:

  • Authentication error
  • Invalid partnerKey
  • Invalid apiKey

Note, too that the stat property indicates that the API call failed. If your API call succeeds, you’ll get a similar response. However, a success response will not have an err section and the stat will be set to ok:

{
    "stat": "ok",
    "domains": [
        "*.janrain.com",
        "*.janraincapture.com",
        "*.localhost",
        "*.rpxnow.com"
    ]
}

Social API error responses are summarized in the following table:

Code Description
–1 Service temporarily unavailable.
0 Missing parameter. Required parameter was not provided.
1 Invalid parameter. Provided parameter was in the wrong format.
1 Could not determine CNAME for custom domain. CNAME for the custom domain is not set in the Engage DB.
1 Supplied domain not found in partner domain whitelist. Custom domain is not in the Engage DB.
1 Invalid realm. This can mean several things: name is too long or too short, realm is too long or contains invalid characters, or the realm or custom domain is already taken by another application.
1 Invalid parameter: {parameter}. The provided parameter is the wrong format.
1 Invalid provider: {provider name}. One of the providers in the provided list is not valid.
1 {provider name} not configured. This provider must be configured before use.
1 Setting permissions not supported for this provider. Provider is invalid or does not have permissions that can be set.
1 Permission does not exist: {permission name}. One of the permissions in the provided list is not valid.
1 Permission not supported for this provider: {permission name}. One of the permissions in the provided list does not exist for this provider.
1 Permission can not be set: {permission name}. One of the permissions in the provided list cannot be set because of the application’s tier (basic, pro, and so on).
2 Data not found.
3 Authentication error.
3 Invalid partnerKey. Provided partner key does not exist.
3 Invalid apiKey. Provided API key does not exist.
4 Facebook error.
5 Mapping exists.
6 Error interacting with a previously operational provider.
7 Engage account upgrade needed to access this API.
8 Missing third-party credentials for this identifier.
9 Third-party credentials have been revoked.
10 Your application is not properly configured.
11 The provider or identifier does not support this feature.
12 Google error.
13 Twitter error.
14 LinkedIn error.
15 LiveIdnerror.
16 MySpace error.
17 Yahoo! error.
18 Domain already exists.
19 App ID not found.

The Social API always generates a 200 HTTP response code, even if the API call fails. Because of that, use the error codes summarized above and the stat property to determine the success or failure of an API call.


Last modified: 6/27/2019