Identity Cloud: Partner API v2

Allows Identity Cloud partners to create social login applications.

Learn more:


Overview

The Partner API enables organization to create social login applications. For example, an online community site could enable users to create their own community sites simply by selecting a few options and then, behind the scenes, having the Partner API create the corresponding applications.

To use the Partner API, you must be an Identity Cloud partner and have a partner key. Contact your Akamai representative for more information.

The Partner API includes the endpoints detailed below.

The /admin endpoints

These endpoints focus on discovery and manipulation of users that have administrative access to a Social Login application:

  • /admin/add
  • /admin/delete
  • /admin/get

The /app endpoints

These endpoints control the creation, deletion, querying, and configuration of Social Login applications:

  • /app/add_domain
  • /app/create
  • /app/create_invite
  • /app/delete
  • /app/get_properties
  • /app/get_provider_permissions
  • /app/reset_api_key
  • /app/set_properties
  • /app/set_provider_permissions
  • /app/verify_domain
  • /apps

Accessing the Partner API endpoints

The Partner API uses the following URL syntax:

https://{partner_domain}/partner/v2/{endpoint}

To access your partner endpoints, replace {partner_domain} with your partner domain name and replace {endpoint} with the appropriate endpoint. For example:

https://akamai-documentation.rpxnow.com/partner/v2/admin/get

Authentication

A standard authentication scheme (such as Basic authentication) is not required to call the Partner APIs. Instead, you must supply both your API key (the apiKey parameter) and your partner key (the partnerKey parameter). Both of these keys can be found on the Settings page of your Social Login Dashboard. Note that partner keys are only available to Identity Cloud partners. Contacts your Akamai representative for more information.

Resources

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

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Administration  
Add an administrator to a relying party POST /api/v2/admin/add{?partnerKey,apiKey,email,verify,format}
Remove an administrator from a relying party POST /api/v2/admin/delete{?partnerKey,apiKey,email,format}
List administrators assigned to a relying party POST /api/v2/admin/get{?partnerKey,apiKey,format}
Applications  
Add a domain to a social login application POST /api/v2/app/add_domain{?domain,partnerKey,apiKey,format}
Create a social login application POST /api/v2/app/create{?name,partnerKey,email,domain,format}
Invite a user to become a social login application administrator POST /api/v2/app/create_invite{?partnerKey,apiKey,email,format}
Delete a social login application POST /api/v2/app/delete{?partnerKey,apiKey,format}
Get property values for a social login application POST /api/v2/app/get_properties{?provider,partnerKey,apiKey,format}
Get application permissions for a social login provider POST /api/v2/app/get_provider_permissions{?provider,partnerKey,apiKey,format}
Reset the API key for a social login application POST /api/v2/app/reset_api_key{?appID,partnerKey,format}
Configure property values for a social login application POST /api/v2/app/set_properties{?provider,partnerKey,apiKey,activityScopesString,consumerKey,contactScopeSet,email,emailPerm,fbAppId,fbSecret,liveidAppId,liveidSecret,liveidPrivacyPolicyUrl,paypalDisplayName,secret,uninstallURL,yahooAppId,format}
Set identity provider permissions for a social login application POST /api/v2/app/set_provider_permissions{?permissions,provider,partnerKey,apiKey,format}
Automate domain verification POST /api/v2/app/verify_domain{?provider,partnerKey,apiKey,code,filename,format}
List all social login applications for a partner POST /api/v2/app/apps{?partnerKey,format}

Add an administrator to a relying party

This call adds an administrator user to a Relying Party. Multiple user entities can be associated to the same email address. When you set verify to false, attempting to add an admin user with such an ambiguous email returns an error.

POST /api/v2/admin/add{?partnerKey,apiKey,email,verify,format}

Sample: /api/v2/admin/add?partnerKey=987654321987654321&apiKey=123456789123456789&email=karim.nafir%40mail.com&verify=true&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
email String karim.nafir@mail.com Email address of the administrator being added.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.
verify Boolean true When set to true (the default value) a verification email is sent to the prospective administrator. The user must click the link in this email before he or she can access the website. If set to false, then user cannot be added as an administrator unless he or she is already an administrator with one or more of the partner relying parties.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode email=example@example.com \
    https://rpxnow.com/partner/v2/admin/add

Remove an administrator from a relying party

This call deletes an admin user on a Relying Party. The API call will not delete an admin if they are the only (non-pending) admin for that RP. The call will respond with an error in this case. In the dashboard, choosing to delete the last admin of an RP will cause the RP to be deleted. The delete API call should be used for that purpose when using the API.

POST /api/v2/admin/delete{?partnerKey,apiKey,email,format}

Sample: /api/v2/admin/delete?partnerKey=987654321987654321&apiKey=123456789123456789&email=karim.nafir%40mail.com&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
email String karim.nafir@mail.com Email address of the administrator being added.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode email=example@example.com  \
    https://rpxnow.com/partner/v2/admin/delete

List administrators assigned to a relying party

This call returns all admin users currently assigned to the Relying Party. It also lists the email associated with each admin user, and if they are subscribed to notifications.

POST /api/v2/admin/get{?partnerKey,apiKey,format}

Sample: /api/v2/admin/get?partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "admins": [
        {
            "email": "somebody@somewhere.com",
            "notify": true
        },
        {
            "email": "somebody2@somewhere.com",
            "notify": false
        }
    ]
}

Sample curl request

curl-X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    https://rpxnow.com/v2/admin/get

Add a domain to a social login application

This call adds a domain to an existing Social Login application.

POST /api/v2/app/add_domain{?domain,partnerKey,apiKey,format}

Sample: /api/v2/app/add_domain?domain=www.example.com&partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
domain String www.example.com Name of the domain being added.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode domain=www.example.com \
    https://rpxnow.com/partner/v2/app/add_domain

Create a social login application

This call creates a new Social Login application. You can use the new application immediately for authenticating with OpenID-enabled providers (Google, AOL, and so on), but non-OpenID providers, such as Facebook, require additional configuration. After calling this function, use set_properties to enable these additional features.

POST /api/v2/app/create{?name,partnerKey,email,domain,format}

Sample: /api/v2/app/create?name=DocumentationApp&partnerKey=987654321987654321&email=karim.nafir%40mail.com&domain=www.example.com&format=xml

Parameter Type Sample Description
Required query parameters
domain String www.example.com Name of the domain being added.
email String karim.nafir@mail.com Email address of the administrator being added.
name String DocumentationApp Name of the new app.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "partnerresponse": {
        "stat": "ok",
        "apikey": "12345678912234567891234567891234567891234",
        "adminurl": "https://rpxnow.com/relying_parties/example",
        "inviteurl": "https://rpxnow.com/invite?code=0123645678901234567890123456789012345678901",
        "realm": "example.rpxnow.com",
        "appid": "01234567890123456789"
    }
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode email=test@example.com \
    --data-urlencode name=example_app \
    --data-urlencode domain=www.example.com \
    https://rpxnow.com/partner/v2/app/create

Invite a user to become a social login application administrator

This call generates an email invitation for administrative access to an existing application.

POST /api/v2/app/create_invite{?partnerKey,apiKey,email,format}

Sample: /api/v2/app/create_invite?partnerKey=987654321987654321&apiKey=123456789123456789&email=karim.nafir%40mail.com&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
email String karim.nafir@mail.com Email address of the administrator being added.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "PartnerResponse": {
        "stat": "ok",
        "inviteUrl": "https://rpxtesting.com/invite?code=12345678912234567891234567891234567891234"
    }
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode email=testing@example.com \
    https://rpxnow.com/partner/v2/app/create_invite

Delete a social login application

This call deletes an existing application. This operation completely removes the Social Login application and is irreversible.

POST /api/v2/app/delete{?partnerKey,apiKey,format}

Sample: /api/v2/app/delete?partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    https://rpxnow.com/partner/v2/app/delete

Get property values for a social login application

This call returns a list of the configured properties for a Social Login application. You can use this in conjunction with /partner/v2/app/set_properties, which can be called after /partner/v2/app/create to configure the application.

POST /api/v2/app/get_properties{?provider,partnerKey,apiKey,format}

Sample: /api/v2/app/get_properties?provider=facebook&partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
provider Enumeration facebook The name of the provider whose properties you want to return, either google, facebook, linkedin, live_id, mixi, myspace, paypal, twitter, tumblr, salesforce, yahoo, orkut, or foursquare. Parameters returned differ by provider.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "fbAppID": "123456789123456",
    "fbSecret": "1234567891234567891234567891234",
    "emailPerm": false,
    "uninstallURL": ""
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode provider=facebook \
    https://rpxnow.com/partner/v2/app/get_properties

Get application permissions for a social login provider

This call returns a Social Login application’s permissions for a provider, as set with the set_provider_permissions call.

POST /api/v2/app/get_provider_permissions{?provider,partnerKey,apiKey,format}

Sample: /api/v2/app/get_provider_permissions?provider=facebook&partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
provider String facebook The name of the provider about which you want information.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "permissions": [
        "readContactsCheckins",
        "manageNotifications",
        "publishCheckins",
        "readCheckins",
        "sendSms",
        "chatLogin",
        "managePages",
        "manageAds",
        "readRequests",
        "readMailbox",
        "rsvpEvent",
        "offlineAccess",
        "onlinePresence",
        "readContactLists",
        "contactsOnlinePresence",
        "createEvent"
    ]
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode provider=google \
    https://rpxnow.com/partner/v2/app/get_properties

Reset the API key for a social login application

This call resets the API key for a given partner Relying Party application.

POST /api/v2/app/reset_api_key{?appID,partnerKey,format}

Sample: /api/v2/app/reset_api_key?appID=jfgfaemlkhjhhmdgkaih&partnerKey=987654321987654321&format=xml

Parameter Type Sample Description
Required query parameters
appID String jfgfaemlkhjhhmdgkaih The application identifier of the RP application for which you want to reset the API key.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "apiKey": "123456789123456789"
}

Sample curl request

curl -X POST \
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode appID=sample_app \
    https://rpxnow.com/partner/v2/app/reset_api_key

Configure property values for a social login application

This call configures Social Login application properties for a given application. Use this function to bind a given application to a given provider. For example, after calling create, use this function to set up a binding to a Facebook application.

POST /api/v2/app/set_properties{?provider,partnerKey,apiKey,activityScopesString,consumerKey,contactScopeSet,email,emailPerm,fbAppId,fbSecret,liveidAppId,liveidSecret,liveidPrivacyPolicyUrl,paypalDisplayName,secret,uninstallURL,yahooAppId,format}

Sample: /api/v2/app/set_properties?provider=google&partnerKey=987654321987654321&apiKey=123456789123456789&activityScopesString=true&consumerKey=12345678912345&contactScopeSet=true&email=karim.nafir%40mail.com&emailPerm=true&fbAppId=177180402838772&fbSecret=0464d84a113e8c29d9dfd352a859c10a&liveidAppId=13bc7f60-9129-11e9-b683-526af7764f64&liveidSecret=gftrjshdfGehdnHJjsjks&liveidPrivacyPolicyUrl=https%3A//documentation.akamai.com/privacy&paypalDisplayName=Karim%20Nafir&secret=56e80a38bcc7cd686281e3c234275b&uninstallURL=https%3A//documentation.akamai.com/facebook-uninstall&yahooAppId=s1tBYM7k&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
provider Enumeration google Name of the provider to be configured, either google, facebook, linkedin, live_id, mixi, myspace, paypal, twitter, renren, salesforce, sinaweibo, soundcloud, yahoo, orkut, or foursquare.
Optional query parameters
activityScopesString Boolean true Yahoo only – Set to true if the user’s Yahoo application has read and write permissions for “Status” and “Updates.” This enables use of Yahoo! with the Sharing solution and the associated activity and set_status API calls. Configuring the permission in the Yahoo! developer portal requires that the application’s consumer key and secret be regenerated.
consumerKey String 12345678912345 Consumer Key for the user’s application. Each provider may implement their consumerKey a little differently, but the parameter name is the same for this API call. This parameter only applies to the following providers – Foursquare, Google, LinkedIn, Mixi, MySpace, Orkut, renren, Salesforce, Sina Weibo, Sound Cloud, Twitter, Yahoo!.
contactScopeSet Boolean true Yahoo only – Set to true if the user’s Yahoo application has read permission for “Contacts.” This enables the get_contacts API call for signed-in Yahoo! users. Configuring the permission in the Yahoo! developer portal requires that the application’s consumer key and secret be regenerated.
email String karim.nafir@mail.com PayPal only – enter a valid email address that is already registered with a PayPal account.
emailPerm Boolean true Facebook only – Set to true if this application needs email to receive end-user email addresses.
fbAppId String 177180402838772 Facebook only – The Application Id for the user’s Facebook application.
fbSecret String 0464d84a113e8c29d9dfd352a859c10a Facebook only – The Application Secret for the user’s Facebook application.
format Enumeration xml Data format for the command response, either xml or the default value of json.
liveidAppId String 13bc7f60-9129-11e9-b683-526af7764f64 Microsoft Account only – The Application ID for the user’s Microsoft Account application.
liveidPrivacyPolicyUrl String https://documentation.akamai.com/privacy Microsoft Account only – The URL for the Microsoft Account application’s privacy policy.
liveidSecret String gftrjshdfGehdnHJjsjks Microsoft Account only – The Secret Key for the user’s Microsoft Account application.
paypalDisplayName String Karim Nafir PayPal only – The display name for the user’s Paypal application.
secret String 56e80a38bcc7cd686281e3c234275b Consumer secret for the user’s application. Each provider may implement the secret a little differently. Supported providers are – foursquare, google, linkedin, mixi, myspace, orkut, renren, salesforce, sinaweibo, soundcloud, twitter, yahoo.
uninstallURL String https://documentation.akamai.com/facebook-uninstall Facebook only – URL invoked when the user uninstalls the Facebook application.
yahooAppId String s1tBYM7k Yahoo only – The Application ID for the user’s Yahoo application.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode provider=google \
    --data-urlencode consumerKey=12345678912345\
    --data-urlencode secret=98765432198765\
    https://rpxnow.com/partner/v2/app/set_properties

Set identity provider permissions for a social login application

This call sets a Social Login application’s permissions for a provider. The permissions that you can set depend on the provider, service level, and whether the provider has been configured or not. You can set permissions if, and only if, you pass them in the permissions parameter. Each request replaces the existing set of permissions. The old ones are cleared and the new ones set.

POST /api/v2/app/set_provider_permissions{?permissions,provider,partnerKey,apiKey,format}

Sample: /api/v2/app/set_provider_permissions?permissions=address%2C%20emails%2C%20interests%2C%20organizations%2C%20photos%2C%20status&provider=yahoo&partnerKey=987654321987654321&apiKey=123456789123456789&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
permissions String address, emails, interests, organizations, photos, status Comma-separated list of permissions to set.
provider Enumeration yahoo Name of the provider, either facebook, google, linkedin, mixi, or paypal.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode partnerKey=987654321987654321\
    --data-urlencode provider=facebook \
    --data-urlencode permissions='address, emails, interests, organizations, photos, status'\
    https://rpxnow.com/partner/v2/app/set_provider_permissions

Automate domain verification

This function automates the server-side component of the provider-specific domain verification mechanism. This function should be called before /partner/v2/app/set_properties to complete the domain verification process. Only Google and Yahoo! support this feature.

POST /api/v2/app/verify_domain{?provider,partnerKey,apiKey,code,filename,format}

Sample: /api/v2/app/verify_domain?provider=yahoo&partnerKey=987654321987654321&apiKey=123456789123456789&code=rCLLGGTVdEiGe%2BDXLHKLCD670B8f99LfK/Ax6sS&filename=YahooVerification&format=xml

Parameter Type Sample Description
Required query parameters
apiKey String 123456789123456789 Social Login API key. This key can be found on the Social Login Dashboard.
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
provider Enumeration yahoo Name of the provider, either google or yahoo.
Optional query parameters
code String rCLLGGTVdEiGe+DXLHKLCD670B8f99LfK/Ax6sS This is the Google-supplied META tag value that will be created on the domain. Use this parameter only when the provider value is google.
filename String YahooVerification This is the Yahoo-supplied filename that will be created on the domain. Use this parameter only when the provider value is yahoo.
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    --data-urlencode apiKey=123456789123456789\
    --data-urlencode provider=google \
    --data-urlencode code=rCLLGGTVdEiGe+DXLHKLCD670B8f99LfK/Ax6sS \
    https://rpxnow.com/partner/v2/app/verify_domain

List all social login applications for a partner

This call lists all applications managed by a partner. This constitutes one parent Relying Party and some number (possibly zero) of child applications, created with create.

POST /api/v2/app/apps{?partnerKey,format}

Sample: /api/v2/app/apps?partnerKey=987654321987654321&format=xml

Parameter Type Sample Description
Required query parameters
partnerKey String 987654321987654321 Social Login partner key. This key can be found on the Social Login Dashboard.
Optional query parameters
format Enumeration xml Data format for the command response, either xml or the default value of json.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "apps": [
        {
            "appId": "12345678912345678912",
            "applicationDomain": "example.janrain.com",
            "apiKey": "12345678912234567891234567891234567891234"
        },
        {
            "appId": "98765432109876543210",
            "applicationDomain": "example2.janrain.com",
            "apiKey": "9876543210987654321098765432109876543210"
        },
        {
            "appId": "01234567890123456789",
            "applicationDomain": "example3.janrain.com",
            "apiKey": "0123456789012345678901234567890123456789"
        }
    ]
}

Sample curl request

curl-X POST \
    --data-urlencode partnerKey=987654321987654321\
    https://rpxnow.com/partner/v2/apps

Data

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

Application

Returns information about all the applications managed by a partner.

Download schema: apps.json

Sample POST response:

{
    "stat": "ok",
    "apps": [
        {
            "appId": "12345678912345678912",
            "applicationDomain": "example.janrain.com",
            "apiKey": "12345678912234567891234567891234567891234"
        },
        {
            "appId": "98765432109876543210",
            "applicationDomain": "example2.janrain.com",
            "apiKey": "9876543210987654321098765432109876543210"
        },
        {
            "appId": "01234567890123456789",
            "applicationDomain": "example3.janrain.com",
            "apiKey": "0123456789012345678901234567890123456789"
        }
    ]
}

Application members

Member Type Description
Application: Returns information about all the applications managed by a partner.
apiKey String Application secret for the application. You can find your application key (also referred to as the application secret) on the Settings page in the Social Login Dashboard.
appId String Unique identifier for the application. You can find your application ID on the Settings page in the Social Login (Engage) Dashboard.
applicationDomain String URL for the application domain. You can find your application domain on the Settings page in the Social Login (Engage) Dashboard.

Errors

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

Error responses

Partner 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"
    ]
}

Partner 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 Partner 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