Janrain Authentication API Documentation

Authentication Endpoints Overview

Access Endpoints

The /access endpoints are used for obtaining codes and tokens that will allow you to perform specific actions on user profiles. An access token will authorize you to access a specific user record without the use of a client ID and secret, and a creation token will authorize you to create new records without a client ID and secret. Authorization codes may be used to obtain a new access token, or they may be used as one-time codes included in password reset links. Verification codes are used as one-time codes included in email verification links.

Oauth Endpoints

The /oauth endpoints may be used to develop a custom authentication and registration experience without using the Janrain Registration widget or Mobile SDKs. An API-only integration built with these endpoints supports social login and registration, traditional login and registration, profile management, social account merging, and password reset and email verification workflows.

Security Schemes

x-janrain-hmac-authorization janrain-signed

Our Registration API supports a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. Using this helps to protect against replay attacks, and ensures that client secrets are well protected.

APID Authorization Headers

Example Request

  GET /entity.find?type_name=user&filter=lastUpdated >= '2016-01-01' HTTP/1.1
  Host: training-pse.janraincapture.com
  Date: 2016-02-26 19:08:44
  Authorization:Signature apkrahlfumwse2e9nvrrotv6vchuptzw:rRSudiGtMM5hEHYcwP49kt18jNk=

Signature

To generate the signature you will need the following:

  • The root-anchored API endpoint (for example /entity.find).
  • The parameters of the API call as key=value pairs, sorted alphabetically and separated by newlines (\n).
  • The date as specified in the Date header in your request.
  • Your client_secret.
  • Your client_id.

To generate the signature:

  1. Concatenate the endpoint, datetime, and sorted parameters with newline characters ('\n'). This creates the string that we will sign.
  2. Use the client_secret to sign the string using SHA-1, then base64 encode the result.
  3. Prepend your client_id to this signature with a colon (:).

The resulting string is a signature that uniquely identifies a single request.

Below we have included a python implementation of the signed header request for further clarity and convenience:

import hmac
from base64 import b64encode
from hashlib import sha1


def make_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) for k, v in params.items()]
    kv_params.sort()
    kv_string = '\n'.join(kv_params)
    str_to_sign = '{}\n{}\n{}\n'.format(endpoint, datetime, kv_string)
    hashed_str = b64encode(hmac.new(secret, str_to_sign, sha1).digest())
    return {'Authorization': 'Signature {}:{}'.format(client_id, hashed_str)}

For code examples in other languages, take a look at our sample code repo.

Authorization string

Used to send the authorization signature.

Example: Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=

Responses

Basic Authentication basic

Our Registration API supports basic HTTP authentication using your application owner credentials. To create the authorization code, combine your client ID and secret like this client_id + ":" + secret, then base64 encode the result. Most RESTful frameworks support basic authentication natively.

Authorization string

Used to send the authorization code.

Example: Authorization: Basic aW1fYV9saXR0bGVfdGVhX3BvdF9zaG9ydF9hbmRfc3Q6b3V0X2hlcmVfaXNfbXlfaGFuZGxlX2hlcmVfaXNfbXk=

Responses

x-janrain-oauth janrain-oauth

Some of our Registration API endpoints support a custom variant of OAuth using access tokens. The following endpoints accept OAuth acccess token authentication:

For more information for this method of authentication, refer to the Use OAuth Authentication topic.

Authorization string

Used to send the access token.

Example: Authorization: OAuth SlAV32hkKG

Responses

Endpoints

https://{app}.janraincapture.com

URI Parameters

app string required

The name of the app domain.

Example: your-app-domain

/access/getAccessToken

Description

This API call retrieves an accessToken for signing in to an application.

get

Description

Example Request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode uuid=78907890wxyzwxyz \
    --data-urlencode type_name=user \
    https://my-app.janraincapture.com/access/getAccessToken

Authorized Clients

owner access_issuer

Security

Query Parameters

uuid string required

Required when not using the id or key_attribute and key_value parameters. The unique identifier given the user entity.

id string required

Required when not using the uuid or key_attribute and key_value parameters.

key_attribute string required

Required when not using id or uuid parameters. This value is any attribute in the schema with a unique constraint.

key_value string required

Required when using key_attribute. This is the value of the unique attribute. Note: String values need to be enclosed in quotes.

type_name string required

The name of the entityType.

for_client_id string

The client_id for which to retrieve an accessToken.

Responses

200 OK

Response Example (application/json)
{
  "accessToken": "tc7blahblah3tmaz",
  "stat": "ok"
}

/access/getAuthorizationCode

Description

Get an authorization code that can be exchanged for an access_token and a refresh_token.

get

Description

Example Request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode redirect_uri=http://foo.janraincapture.com/oauth/flags=stay_in_window \
    --data-urlencode id=4 \
    https://my-app.janraincapture.com/access/getAuthorizationCode

Authorized Clients

owner access_issuer

Security

Query Parameters

uuid string required

Required when not using the id or key_attribute and key_value paramaters. The unique identifier given the user entity.

id string required

Required when not using the uuid or key_attribute and key_value parameters.

key_attribute string required

Required when not using id or uuid parameters. This value is any attribute in the schema with a unique constraint.

key_value string required

Required when using key_attribute. This is the value of the unique attribute. Note: String values need to be enclosed in quotes.

redirect_uri string required

The redirect URI. This is the address used by the UI to make the redirect.

type_name string required

The entityType of the entity.

transaction_state string

A JSON object that will be associated with the authorization code and returned when it is exchanged for an access_token and a refresh token. You determine what data is returned.

lifetime string

The number of seconds for which the code is valid. The default value is 30 seconds.

for_client_id string

The client_id for which to retrieve an authorization code.

Responses

200 OK

Response Example (application/json)
{
  "authorizationCode": "12345678912345",
  "stat": "ok"
}

/access/getCreationToken

Description

Gets a creation token which can be used to make entity.create calls without the use of a client id and secret.

This is targeted for mobile developers who do not want to expose their credentials to untrusted (any) mobile devices.

get

Description

Example Request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode type_name=user \
    --data-urlencode lifetime=3600 \
    --data-urlencode for_client_id=fghi7890fghi7890 \
    https://my-app.janraincapture.com/access/getCreationToken

Authorized Clients

owner access_issuer

Security

Query Parameters

type_name string required

The entityType of the entity that will be created with this token.

lifetime string required

The number of seconds for which this token is valid. The lifetime value must be configured per application. If not provided, the creation token defaults to 1 hour.

for_client_id string required

The client id to which you wish to grant the creation token. This is useful if you have read and write schemas specific to client ids in your system.

Responses

200 OK

Response Example (application/json)
{
  "stat": "ok",
  "creation_token": "1234567891234567"
}

/access/getVerificationCode

Description

Gets a verification code that can later be used with useVerificationCode. The useVerificationCode call sets a time field in an entity to the current time. This is useful for recording timestamps for when an email address was verified, or similar purposes.

get

Description

Example Request

The example shows a request that gets a verification code for setting an attribute named "emailVerified" in the Person entity with an id of 1.

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode id=1 \
    --data-urlencode type_name=Person \
    --data-urlencode attribute_name=emailVerified \
    https://my-app.janraincapture.com/access/getVerificationCode

Authorized Clients

owner direct_access

Security

Query Parameters

uuid string required

Required when not using id or the key_attribute and key_value parameters. The unique identifier given the user entity.

id string required

The id number associated with the user record.

key_attribute string required

Required when not using the id or uuid parameters. This value is any attribute in the schema with a unique constraint.

key_value string required

Required when using the key_attribute. This is the value of the unique attribute. Note: String values need to be enclosed in quotes.

type_name string required

The entityType of the entity.

attribute_name string required

The name of the attribute to update when using the verification code.

lifetime string

The number of seconds this verification code is valid for. If you do not provide a value, the default lifetime is equal to seven days (604800 seconds).

Responses

200 OK

Response Example (application/json)
{
  "verification_code": "htjwg2uphwz5mqxrnqe4tuvpxkzaqrr5",
  "stat": "ok"
}

/access/useVerificationCode

Description

Uses a verification code to set a time field to the current time. Any particular verification code can only be used once. This is often used for items like email verification.

get

Description

Example Request

curl --data-urlencode verification_code=12345678912345678912345678912345 \
    https://my-app.janraincapture.com/access/useVerificationCode

Authorized Clients

no-auth-required

Security

Query Parameters

verification_code string required

The verification code obtained in a previous call to access/getVerificationCode.

Responses

200 OK

Example Error Response

{
    "argument_name": "verification_code",
    "request_id": "fvdfxwpxew2qe76p",
    "code": 200,
    "error_description": "verification code not recognized",
    "error": "invalid_argument",
    "stat": "error"
}
Response Example (application/json)
{
  "stat": "ok",
  "uuid": "7d19b6f2-bba2-48ba-9442-19d396427d77"
}

/oauth/auth_native

Description

This endpoint is used to complete social login. To make this call, you must have a valid Social Login token received after a user successfully authenticates through one of the identity providers you have enabled for your Social Login application. See Implementing Social Login for more information on how to get Social Login tokens.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example 1: Complete Social Authentication

The example below shows a typical call to complete social authentication for a user after a Social Login token is received.

curl -X POST \
  --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
  --data-urlencode 'flow=standard' \
  --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'redirect_uri=http://localhost' \
  --data-urlencode 'response_type=token' \
  --data-urlencode 'registration_form=socialRegistrationForm' \
  --data-urlencode 'token=ab12cd34ef56gh78ij90kl12mn34op56qr78st78' \
  'https://my-app.janraincapture.com/oauth/auth_native'

If the user does not exist in the Janrain Registration database, the error response will include profile information from the IDP that can be used to register the user via a call to oauth/register_native. Only data defined in the form specified in the registration_form parameter will be returned in this error response.

Example 2: Merge Social Accounts

The next example shows a call made to merge a new social account into an existing user record. The token parameter uses a Social Login token for the account that already exists in your Registration database, and the merge_token parameter uses a Social Login token for the new account through which the user has authenticated.

curl -X POST \
  --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
  --data-urlencode 'flow=standard' \
  --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'redirect_uri=http://localhost' \
  --data-urlencode 'response_type=token' \
  --data-urlencode 'token=12ab34cd56ef78gh90ij12kl34mn56op78qr90st' \
  --data-urlencode 'merge_token=ab12cd34ef56gh78ij90kl12mn34op56qr78st78' \
  'https://my-app.janraincapture.com/oauth/auth_native'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features API.

flow string required

The name of the flow configured with the social login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

locale string required

The code for the language you want to use for the social login experience. This will determine the language for any error messages returned to you. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

merge_token string

If you have had a previous call fail with code 380 email_address_in_use, you can merge the new social account into the existing one by including the merge_token parameter in this call or the auth_native_traditional call authenticating the user's existing account. The token value for this parameter must be the same token from the previous failed auth_native call.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http:, or https:, and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

registration_form string

The name of the form in your flow that you will use for social registration. This parameter determines what is included in the error response if no existing record is found with the same email address returned by the social provider after a successful authentication. When set, the response will include values for prereg_fields, which includes data from the social provider's payload mapped to fields in your social registration form. You can use this data to pre-populate the parameters for the oauth/register_native. The default form name for social registration configured for the standard flow is socialRegistrationForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the social registration form in widget-based implementations (for example, {* #socialRegistrationForm *}).

response_type string

Values are code, token, or code_and_token. This determines whether you will receive an access token, an authorization code, or both after a user is successfully registered or authenticated. If omitted, the response type will default to token. This parameter corresponds to the janrain.settings.capture.responseType JavaScript setting used in widget-based implementations.

thin_registration boolean

Values are true or false. This parameter determines the behavior of the auth_native call if no existing record is found with the same email address returned by the social provider after a successful authentication. If true, this endpoint will create a new record immediately, and social data will be stored in the profiles section of the user record. The standard flow provisioned with Registration applications is also configured to copy social data, if available, to the top-level schema attributes for email, displayName, givenName, and familyName upon record creation. If set to false or omitted from the call, you will need to complete two-step registration using oauth/register_native. See the registration_form parameter for info on how to gather data from the social provider response for use in the social registration form.

token string required

A one-time token used for social authentication. This is the token passed from the Social Login application to your token URL. It must be received from the same Social Login application that is configured for the API client used to make this call; this may be configured in the Default Settings for your Registration application if you have a single Social Login application. The token will be a unique 40 character string. This token may also be used with the auth_info endpoint to retrieve a user's social profile directly, but this is not necessary when using these oauth endpoints for registration since that data is retrieved and stored for you.

Responses

200 OK

Successful Response

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

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

Error - User Not Yet Registered

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

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

Error - Email Address Already Registered

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

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

Error - Invalid Social Login Token

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

{
  "stat": "error",
  "code": 200,
  "error_description": "invalid token",
  "error": "invalid_argument",
  "request_id": "zygzvaatua8ezk2v"
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/auth_native_traditional

Description

This endpoint is used to complete traditional login using an email address or username along with a password.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example: Complete Traditional Authentication

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'redirect_uri=http://localhost' \
    --data-urlencode 'response_type=token' \
    --data-urlencode 'form=signInForm' \
    --data-urlencode 'signInEmailAddress=johndoe@example.com' \
    --data-urlencode 'currentPassword=password123' \
    'https://my-app.janraincapture.com/oauth/auth_native_traditional'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features API.

flow string required

The name of the flow configured with the traditional login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for traditional authentication. This will determine what field names you will need to include when submitting this API call. The default form name for traditional authentication configured for the standard flow is signInForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the sign-in form in widget-based implementations (for example, {* #signInForm *}).

(form fields) string required

The names of any fields that are configured in your flow with the traditional login form. Each field must be passed as a separate parameter; you will use the field name as the key and the user input as the value. All fields configured as required in the flow for that form must be included. The default traditional authentication fields configured for the standard flow are signInEmailAddress and currentPassword. You can find a list of valid fields for your traditional registration form using the Configuration API. These field names correspond to the name of the JTL tags included inside the associated form in widget-based implementations.

locale string required

The code for the language you want to use for the login experience. This will determine the language for any error messages returned to you. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

merge_token string

If you have had a previous oauth/auth_native call fail with code 380 email_address_in_use, you can merge the new social account into the existing one by including the merge_token parameter in this call while authenticating the user's existing account. The token value for this parameter must be the same token from the previous failed auth_native call.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http: or https:, and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

response_type string

Values are code, token, or code_and_token. This determines whether you will receive an access token, an authorization code, or both after a user is successfully authenticated. If omitted, the response type will default to token. This parameter corresponds to the janrain.settings.capture.responseType JavaScript setting used in widget-based implementations.

Responses

200 OK

Successful Response

A successful response will return the user profile in the capture_user object along with an access_token or authorization_code depending on the response_type parameter you included in the call.

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

Error - Invalid Credentials

The example error response below indicates that traditional authentication failed. The same error message will be returned if the email address is not registered or if the email address is registered but the password entered is incorrect.

{
  "stat": "error",
  "code": 210,
  "error_description": "some inputs are invalid",
  "error": "invalid_credentials",
  "request_id": "5442cd9rdkcayy3p",
  "invalid_fields": {
    "signInForm": [
      "Incorrect username or password. Please try again."
    ]
  }
}

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case-sensitive, so signinform would fail if signInForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'signinform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/forgot_password_native

Description

This endpoint is used to trigger an email that includes a link with a one-time authorization code a user can click to set a new password. The destination URL for this link is configured in the password_recover_url setting for the API client used to make this call.

If you are not utilizing the Janrain JavaScript widget at this URL, you will need to use the oauth/token call to consume the authorization code and exchange it for an access token. You must use the same API client when making the oauth/forgot_password_native call to generate the code and when making the oauth/token call to consume it. If successful, you can proceed to use the oauth/update_profile_native call to update the user's password. If unsuccessful, this API can be used again to resend an email with a new code.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example: Trigger Forgot Password Email

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'redirect_uri=http://localhost' \
    --data-urlencode 'form=forgotPasswordForm' \
    --data-urlencode 'signInEmailAddress=johndoe@example.com' \
    'https://my-app.janraincapture.com/oauth/forgot_password_native'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for generating the password reset email. This will determine what field names you will need to include when submitting this API call. The default form name for password reset configured for the standard flow is forgotPasswordForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the forgot password form in widget-based implementations (for example, {* #forgotPasswordForm *}).

(form fields) string required

The name of the field that is configured in your flow with the form used to generate the password reset email. You will use the field name as the key and the user input as the value for this parameter. The default forgotPasswordForm configured for the standard flow uses the field signInEmailAddress. You can find a list of valid fields and associated forms for your flow using the Configuration API. This field name corresponds to the JTL tag used for the email field in your forgot password form in widget-based implementations.

locale string required

The code for the language you want to use for the login experience. This will determine the language for any error messages returned to you and the reset password emails sent to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

redirect_uri string required

This parameter must match the value configured for the password_recover_url setting for the API client used to make this call. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

Responses

200 OK

Successful Response

A successful call will return the simple response below:

{
  "stat": "ok"
}

Error - Email Does Not Exist

The example error response below indicates that the email address submitted is not registered, so no email will be sent. The invalid_fields object will include a localized error message from the flow.

{
  "stat": "error",
  "code": 212,
  "error_description": "some inputs are invalid",
  "error": "no_such_account",
  "request_id": "hyhrbds6f4ws4vav",
  "invalid_fields": {
    "forgotPasswordForm": [
      "No account with that email address exists."
    ]
  }
}

Error - Field Validation Errors

The example error response below indicates that the email address submitted is registered for an account that has no password, usually because it was created with a social identity. No email will be sent in this case. The message attribute will include a localized error message from the flow. Your flow may be configured to bypass this error and send the email if desired.

{
  "stat": "error",
  "code": 540,
  "error_description": "an error was triggered in the flow",
  "error": "triggered_error",
  "request_id": "rspc2skdu7arex82",
  "message": "That account is social signin only."
}

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case-sensitive, so forgotpasswordform would fail if forgotPasswordForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'forgotpasswordform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/link_account_native

Description

This endpoint is used to link a new social identity to an existing user account. Once linked, the new identity can be used to sign in to that account. To make this call, you must have a valid Social Login token received after a user authenticates through the social provider account to be linked, as well as a valid Registration access token for the user record to be updated.

Example

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

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

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

Authorized Clients

login_client

Security

Query Parameters

access_token string required

A Registration access token, which will be returned after authentication or registration with a previous call (/oauth/auth_native, /oauth/auth_native_traditional, and so on) if the response_type parameter is set to token. If set to code, you will need to exchange the authorization code for an access token using the /oauth/token call.

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the profile management experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

locale string required

The code for the language you want to use for the profile management experience. This will determine the language for any error messages returned to you. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http: or https:, and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

token string required

A one-time token used for social authentication. This is the token passed from the Social Login application to your token url. It must be received from the same Social Login application that is configured for the API client used to make this call; this may be configured in the Default Settings for your Registration application if you have a single Social Login application. The token will be a unique 40-character string. This token could be used with the auth_info endpoint to retrieve a user's social profile directly, but this is not necessary when using these oauth endpoints for registration since that data is retrieved and stored for you.

Responses

200 OK

Successful Response

A successful call will return the simple response below:

{
  "stat": "ok"
}

Error - Invalid Social Login Token

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

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

Error - Invalid Registration Access Token

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

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

Error - Social Account Already Used

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

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

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/register_native

Description

This endpoint is used to complete social registration. To make this call, you first make a call to oauth/auth_native for two reasons:

  1. oauth/register_native will not accept the token if you have not called oauth/auth_native first.
  2. If you included the registration_form parameter in the call to oauth/auth_native, the data from the social provider's payload can be used to pre-populate fields in your social registration form.

Then, you can take the same Social Login token you used in the oauth/auth_native call and use it in the oauth/register_native call.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example: Complete Social Registration

Note that if you attempt to call oauth/register_native without first calling oauth/auth_native, then you will receive an error stating the Social Login token is invalid.

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'redirect_uri=http://localhost' \
    --data-urlencode 'token=12ab34cd56ef78gh90ij12kl34mn56op78qr90st' \
    --data-urlencode 'form=socialRegistrationForm' \
    --data-urlencode 'emailAddress=janedoe@example.com' \
    --data-urlencode 'lastName=Doe' \
    --data-urlencode 'firstName=Jane' \
    --data-urlencode 'displayName=JaneDoe' \
    'https://my-app.janraincapture.com/oauth/register_native'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the social registration experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for social registration. This will determine what field names you will need to include when submitting this API call. The default form name for social registration configured for the standard flow is socialRegistrationForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the social registration form in widget-based implementations (for example, {* #socialRegistrationForm *}).

(form fields) string required

The names of any fields that are configured in your flow with the social registration form. Each field must be passed as a separate parameter; you will use the field name as the key and the user input as the value. All fields configured as required in the flow for that form must be included. The default socialRegistrationForm configured for the standard flow includes emailAddress, firstName, lastName, and displayName as required fields. You can find a list of valid fields for your traditional registration form using the Configuration API. These field names correspond to the name of the JTL tags included inside the associated form in widget-based implementations.

locale string required

The code for the language you want to use for the registration experience. This will determine the language for any error messages returned to you and any registration confirmation emails sent to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http: or https: and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

response_type string

Values are code, token, or code_and_token. This determines whether you will receive an access token, an authorization code, or both after a user is successfully registered or authenticated. If omitted, the response type will default to token. This parameter corresponds to the janrain.settings.capture.responseType JavaScript setting used in widget-based implementations.

token string required

A one-time token used for social authentication. This is the token passed from the Social Login application to your token url. It must be received from the same Social Login application that is configured for the API client used to make this call; this may be configured in the Default Settings for your Registration application if you have a single Social Login application. The token will be a unique 40-character string. This token may be used with the auth_info endpoint to retrieve a user's social profile directly, but this is not necessary when using these oauth endpoints for registration since that data is retrieved and stored for you.

Responses

200 OK

Successful Response

A successful response will return the user profile in the capture_user object along with an access_token or authorization_code depending on the response_type parameter you included in the call.

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

Error - Invalid Social Login Token

The example error response below indicates that the Social Login token passed into the call is invalid or expired. Note that you will also see this error if you have not called oauth/auth_native first.

{
  "stat": "error",
  "code": 200,
  "error_description": "the token you passed was not valid",
  "error": "invalid_argument",
  "request_id": "f5q326y8ef2tmfcq"
}

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case sensitive, so socialregistrationform would fail if socialRegistrationForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'socialregistrationform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Field Validation Errors

The example error response below indicates that validation failed for some fields configured with the form used in the call. All validation rules for these fields are checked, so you may receive errors for multiple fields and multiple errors on a single field. Validation errors are commonly encountered when a required field is missing, the email address or another unique field is already taken, or the user input does not pass formatting validation applied to a field. The invalid_fields object will include field names mapped to a list of localized error messages from the flow for each validation that failed.

{
  "stat": "error",
  "code": 390,
  "error_description": "some inputs are invalid",
  "error": "invalid_form_fields",
  "request_id": "eyt2p5thkwch5h2h",
  "invalid_fields": {
    "displayName": [
      "That display name is already taken."
    ],
    "emailAddress": [
      "Email address is required."
    ]
  }
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/register_native_traditional

Description

This endpoint is used to complete traditional registration. Once complete, a user will be able to authenticate using an email address or username along with a password.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example: Complete Traditional Registration

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'redirect_uri=http://localhost' \
    --data-urlencode 'response_type=token' \
    --data-urlencode 'form=registrationForm' \
    --data-urlencode 'emailAddress=johndoe@example.com' \
    --data-urlencode 'newPassword=password123' \
    --data-urlencode 'newPasswordConfirm=password123' \
    --data-urlencode 'lastName=Doe' \
    --data-urlencode 'firstName=John' \
    --data-urlencode 'displayName=JohnDoe' \
    'https://my-app.janraincapture.com/oauth/register_native_traditional'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the traditional registration experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for traditional registration. This will determine what field names you will need to include when submitting this API call. The default form name for traditional registration configured for the standard flow is registrationForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the JTL tag used for the associated form in widget-based implementations (for example, {*#registrationForm *}).

(form fields) string required

The names of any fields that are configured in your flow with the traditional registration form. Each field must be passed as a separate parameter; you will use the field name as the key and the user input as the value. All fields configured as required in the flow for that form must be included. The default registrationForm configured for the standard flow includes emailAddress, newPassword, newPasswordConfirm, firstName, lastName, and displayName as required fields. You can find a list of valid fields for your traditional registration form using the Configuration API. These field names correspond to the name of the JTL tags included inside the associated form in widget-based implementations.

locale string required

The code for the language you want to use for the registration experience. This will determine the language for any error messages returned to you and any registration confirmation emails sent to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http: or https: and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

response_type string

Values are code, token, or code_and_token. This determines whether you will receive an access token, an authorization code, or both after a user is successfully registered or authenticated. If omitted, the response type will default to token. This parameter corresponds to the janrain.settings.capture.responseType JavaScript setting used in widget-based implementations.

Responses

200 OK

Successful Response

A successful response will return the user profile in the capture_user along with an access_token or authorization_code depending on the response_type parameter you included in the call.

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

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case sensitive, so registrationform would fail if registrationForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'registrationform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Field Validation Errors

The example error response below indicates that validation failed for some fields configured with the form used in the call. All validation rules for these fields are checked, so you may receive errors for multiple fields and multiple errors on a single field. Validation errors are commonly encountered when a required field is missing, the email address or another unique field is already taken, or the user input does not pass formatting validation applied to a field. The invalid_fields object will include field names mapped to a list of localized error messages from the flow for each validation that failed.

{
  "stat": "error",
  "code": 390,
  "error_description": "some inputs are invalid",
  "error": "invalid_form_fields",
  "request_id": "eyt2p5thkwch5h2h",
  "invalid_fields": {
    "displayName": [
      "That display name is already taken."
    ],
    "emailAddress": [
      "Email address is required."
    ],
    "newPasswordConfirm": [
      "Passwords do not match."
    ]
  }
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/token

Description

This endpoint can be used to obtain a Registration access_token for an authenticated user. You will need to exchange either an authorization_code or a refresh_token in order to get a new access_token. An authorization_code may be generated when a user is authenticated through the Janrain widget or through the oauth/auth_native, oauth/register_native, oauth/auth_native_traditional, or oauth/register_native_traditional endpoints if your response type has been set to code. Authorization codes may also be obtained through the /access/getAuthorizationCode endpoint.

A refresh_token is returned in the response each time this call is made and may be used for subsequent calls to obtain a new access_token. A refresh_token is valid for one use only, so a new one must be used for each subsequent call.

An access_token is valid for one hour, so you can use this API or the /access/getAccessToken endpoint to request a new one in order to keep a user authenticated through Janrain for the length of your site or application's session.

get

Description

Example 1: Exchange Authorization Code for Access Token

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=7n12d0snfps1bb' \
--data-urlencode 'redirect_uri=http://example.com' \
https://my-app.janraincapture.com/oauth/token

Example 2: Exchange Refresh Secret for Access Token

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=bjkxc67m3nkva2bd982z' \
https://my-app.janraincapture.com/oauth/token

Authorized Clients

owner login_client direct_read_access direct_access access_issuer
Note: While any client can exchange an authorization_code for an access_token, that code must have been provisioned for that client (e.g., specifying a value in for_client_id when generating a code via oauth/getAuthorizationCode)

Security

Query Parameters

grant_type string required

Available values are authorization_code and refresh_token. The grant_type identifies what type of access grant you are passing into the call. If this is set to refresh_token, then you must supply the refresh_token parameter. If this is set to authorization_code, then you must supply the code parameter.

code string required

The authorization code received after a user has successfully authenticated or after you have made a call to the /access/getAuthorizationCode API. This parameter is required only when the grant_type is set to authorization_code.

redirect_uri string required

The same value as the redirect_uri that was passed into a previous API call to obtain an authorization_code or the redirectUri setting configured in a widget-based implementation. This parameter is required only when the grant_type is set to authorization_code.

refresh_token string

A refresh token received from a previous oauth/token call. A new pair of access and refresh tokens will be returned. This parameter is required only when the grant_type is set to refresh_token.

Responses

200 OK

Successful Response

A successful response will include a new pair of access and refresh tokens along with the access_token expiration time in seconds.

{
  "access_token": "8r8v9ad6dajnbk5t",
  "expires_in": 3600,
  "refresh_token": "f4mrz7dzatqm272tpey2",
  "stat": "ok"
}

Error - Invalid Authorization Code

The example error response below indicates that the authorization_code included in the call is not valid. This may be encountered when the code has expired, has already been used, or when the client ID that was used to generate the code does not match the client ID used to make the oauth/token call.

{ "request_id": "8sphe693btp8hgv4", "code": 413, "error_description": "authorization_code is not valid", "sub_error": "no_access_grant", "error": "invalid_request", "stat": "error" }

Error - Invalid Redirect URI

The example error response below indicates that the redirect_uri included in the oauth/token call does not match the value that was used when generating the code passed into the authorization_code parameter.

{
  "received_value": "http://localhost",
  "request_id": "hbpbfre9qnsbpjbv",
  "code": 420,
  "expected_value": "http://localhost2",
  "error_description": "redirect_uri does not match expected value",
  "sub_error": "redirect_uri_mismatch",
  "error": "invalid_request",
  "stat": "error"
}

Error - Invalid Refresh Token

The example error response below indicates that the refresh_token included in the call is not valid. This may be encountered when the token has expired or has already been used.

{
  "request_id": "rgg3nzte9kakua38",
  "code": 200,
  "error_description": "unknown refresh_token",
  "sub_error": "invalid_argument",
  "error": "invalid_request",
  "stat": "error"
}

Error - Invalid API Client Permissions

The example error response below indicates that API client credentials used to authenticate the call are not valid for the Registration application.

{
  "request_id": "mzzufjfz8hvyzemd",
  "code": 402,
  "error_description": "credentials are not valid",
  "sub_error": "invalid_client_credentials",
  "error": "invalid_client",
  "stat": "error"
}

/oauth/unlink_account_native

Description

This endpoint is used to unlink a social provider from a user account. Once unlinked, the social provider cannot be used to sign into that account. To make this call, you must have a valid Registration access token for the user record to be updated.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'access_token=z0y98xv76u5t4rs3' \
    --data-urlencode 'identifier_to_remove=http://www.example.com/profile/1234567890' \
    'https://my-app.janraincapture.com/oauth/unlink_account_native'

Authorized Clients

login_client

Security

Query Parameters

access_token string required

A Registration access token, which will be returned after authentication or registration with a previous call (/oauth/auth_native, /oauth/auth_native_traditional, and so on) if the response_type parameter is set to token. If set to code, you will need to exchange the authorization code for an access token using the /oauth/token call.

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the profile management experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

identifier_to_remove string required

The identifier URL for the social account you want to unlink. You can find available social identifier URLs for a user record by making an /entity API call filtering for profiles.identifier.

locale string required

The code for the language you want to use for the profile management experience. This will determine the language for any error messages returned to you. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

Responses

200 OK

Successful Response

A successful call will return the simple response below:

{
  "stat": "ok"
}

Error - Invalid Registration Access Token

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

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

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/update_profile_native

Description

This endpoint is used to update profile data based on input from a user in an edit profile form. To make this call, you must have a valid Registration access token for the user record to be updated.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example 1: Update Profile Data

The example below shows a call made to update the user's displayName from a profile page that is accessible after a user has logged in.

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'form=editProfileForm' \
    --data-urlencode 'displayName=JaneDoe' \
    --data-urlencode 'access_token=z0y98xv76u5t4rs3' \
    'https://my-app.janraincapture.com/oauth/update_profile_native'

Example 2: Change Password from Profile

The example below shows a call made to update a user's password from a profile page that is accessible after a user has logged in. In this case the user must provide the existing password as well as the new password to be saved.

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'form=changePasswordForm' \
    --data-urlencode 'currentPassword=password123' \
    --data-urlencode 'newPassword=Password1' \
    --data-urlencode 'newPasswordConfirm=Password1' \
    --data-urlencode 'access_token=z0y98xv76u5t4rs3' \
    'https://my-app.janraincapture.com/oauth/update_profile_native'

Example 3 - Change Password from Reset Password Email

The example below shows another call made to update a user's password. Unlike the example above, the user has forgotten the password and requested a reset password email. This form does not require the user's existing password to be included. Prior to making this call, you will need to validate the authorization code passed to your reset password page and exchange it for an access token. See the oauth/forgot_password_native endpoint for more information on this workflow.

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'form=changePasswordFormNoAuth' \
    --data-urlencode 'newPassword=Password2' \
    --data-urlencode 'newPasswordConfirm=Password2' \
    --data-urlencode 'access_token=z0y98xv76u5t4rs3' \
    'https://my-app.janraincapture.com/oauth/update_profile_native'

Authorized Clients

login_client

Security

Query Parameters

access_token string required

A Registration access token, which will be returned after authentication or registration with a previous call (/oauth/auth_native, /oauth/auth_native_traditional, and so on) if the response_type parameter is set to token. If set to code, you will need to exchange the authorization code for an access token using the /oauth/token call.

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the profile management experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for profile updates. This will determine what field names you will need to include when submitting this API call. The default form name for user profile management configured for the standard flow is editProfileForm. Other default form names that can be used in this call are newPasswordForm and newPasswordFormNoAuth. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the associated form in widget-based implementations (for example, {* #editProfileForm *}).

(form fields) string required

The names of any other fields that are configured in your flow with a profile management form. Each field must be passed as a separate parameter; you will use the field name as the key and the user input as the value. All fields configured as required in the flow for the form passed in the call must be included if the user record does not have existing data stored in the associated attribute. The default editProfileForm provisioned for the standard flow includes emailAddress, firstName, lastName, and displayName as required fields and several others as optional. You can find a list of valid fields for your profile management forms using the Configuration API. These field names correspond to the name of the JTL tags included inside the associated form in widget-based implementations.

locale string required

The code for the language you want to use for the profile management experience. This will determine the language for any error messages returned to you and any emails sent by Janrain to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

Responses

200 OK

Successful Response

A successful call will return the simple response below:

{
  "stat": "ok"
}

Error - Invalid Registration Access Token

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

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

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case sensitive, so editprofileform would fail if editProfileForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'editprofileform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Field Validation Errors

The example error response below indicates that validation failed for some fields configured with the form used in the call. All validation rules for these fields are checked, so you may receive errors for multiple fields and multiple errors on a single field. Validation errors are commonly encountered when a required field is missing, the email address or another unique field is already taken, or the user input does not pass formatting validation applied to a field. Note that if the user record does not have existing data stored for any field configured as required in the flow for the form passed in the call, that field must be included as a parameter. The invalid_fields object will include field names mapped to a list of localized error messages from the flow for each validation that failed.

{
  "stat": "error",
  "code": 390,
  "error_description": "some inputs are invalid",
  "error": "invalid_form_fields",
  "request_id": "eyt2p5thkwch5h2h",
  "invalid_fields": {
    "displayName": [
      "That display name is already taken."
    ],
    "lastName": [
      "Last Name is required."
    ]
  }
}

Error - Invalid Credentials

The example error response below indicates that the value entered for the user's current password failed on the change password form. The invalid_fields object will include a localized error messages from the flow.

{
  "stat": "error",
  "code": 210,
  "error_description": "some inputs are invalid",
  "error": "invalid_credentials",
  "request_id": "zqnw6qzqxy2yvee8",
  "invalid_fields": {
    "changePasswordForm": [
      "Current password is incorrect. Please try again."
    ]
  }
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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

/oauth/verify_email_native

Description

This endpoint is used to trigger an email that includes a link with a one- time verification code a user can click to complete the email verification process. The destination URL for this link is configured in the verify_email_url setting for the API client used to make this call.

If you are not utilizing the Janrain JavaScript widget at this URL, you will need to use the access/useVerificationCode endpoint to consume the verification code. If successful, the emailVerified attribute in the user's record will be set with the current timestamp. If unsuccessful, this endpoint can be used again to resend an email with a new code.

Note: This must be a POST request with all parameters included in the body of the request; they cannot be passed as URL parameters.

post

Description

Example: Trigger Verification Email

  curl -X POST \
    --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
    --data-urlencode 'flow=standard' \
    --data-urlencode 'flow_version=67890def-6789-defg-6789-67890defgh67' \
    --data-urlencode 'locale=en-US' \
    --data-urlencode 'redirect_uri=http://localhost' \
    --data-urlencode 'form=resendVerificationForm' \
    --data-urlencode 'signInEmailAddress=johndoe@example.com' \
    'https://my-app.janraincapture.com/oauth/verify_email_native'

Authorized Clients

login_client

Security

Query Parameters

client_id string required

The API client ID that will be used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured in the Janrain Dashboard or the clients/set_features endpoint.

flow string required

The name of the flow configured with the login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in widget- based implementations. The default flow provisioned with Registration applications is called standard. If you have multiple flows, you can find a list of valid flow names using the Configuration API. You may omit this parameter if you configure the flow name in the default_flow_name setting for the API client used to make this call.

flow_version string required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in widget-based implementations; however, this call will not accept a version of HEAD as the setting does. You must specify the version number if you want to use the most recent version. You can find a list of versions for your flow using the Configuration API. You may omit this parameter if you configure the flow version in the default_flow_version setting for the API client used to make this call.

form string required

The name of the form in your flow that you want to post user input to for generating the verification email. This will determine what field names you will need to include when submitting this API call. The default form name for email verification configured for the standard flow is resendVerificationForm. You can find a list of valid forms and associated fields for your flow using the Configuration API. This form name corresponds to the name of the JTL tag used for the associated form in widget-based implementations (for example, {* #socialRegistrationForm *}).

(form fields) string required

The name of the field that is configured in your flow with the form used to generate the verification email. You will use the field name as the key and the user input as the value for this parameter. The default resendVerificationForm configured for the standard flow uses the field signInEmailAddress. You can find a list of valid fields and associated forms for your flow using the Configuration API. This field name corresponds to the JTL tag used for the email field in your resend verification form in widget-based implementations.

locale string required

The code for the language you want to use for the login experience. This will determine the language for any error messages returned to you and the verification emails sent to users. This parameter corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.

redirect_uri string required

This parameter is required for legacy purposes and is not used for any functionality in this call. It must begin with http: or https: and we recommend that this match the URL and protocol of your website. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in widget-based implementations.

Responses

200 OK

Successful Response

A successful call will return the simple response below:

{
  "stat": "ok"
}

Error - Email Does Not Exist

The example error response below indicates that the email address submitted is not registered, so no email will be sent. The invalid_fields object will include a localized error message from the flow.

{
  "stat": "error",
  "code": 210,
  "error_description": "some inputs are invalid",
  "error": "invalid_credentials",
  "request_id": "v2ddw6xyc2s39tm3",
  "invalid_fields": {
    "resendVerificationForm": [
      "We don't recognize that email address. Please try again."
    ]
  }
}

Error - Email Already Verified

The example error response below indicates that the email address submitted has already been verified, so no email will be sent. The message attribute will include a localized error message from the flow.

{
  "stat": "error",
  "code": 540,
  "error_description": "an error was triggered in the flow",
  "error": "triggered_error",
  "request_id": "g3cfbjg9ptge2yte",
  "message": "Your email is already verified. You may sign in."
}

Error - Invalid Form

The example error response below indicates that the form value is not valid for the flow included in the call. Form names are case sensitive, so resendverificationform would fail if resendVerificationForm is the valid form name.

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'resendverificationform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

Error - Missing Required Parameters

The example error response below indicates that one of the required parameters for the call was not included. The error message will describe which parameter is missing.

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

Error - Invalid Flow Value

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

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

Error - Invalid API Client Permissions

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

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