Identity Cloud: Authentication API v2

Create and employ authorization codes, access tokens, and verification codes for Identity Cloud.

Learn more:


Overview

The Authentication API enables you to create and employ authorization codes, access tokens, and verification codes. You can also use this API to log users on to a website or application using either traditional logon or social logon. The Authentication API includes the endpoints detailed below.

The /access endpoints

The /access endpoints are used for obtaining codes and tokens that allow you to perform specific actions on user profiles. For example, an access token authorizes you to access a specific user record without the use of a client ID and secret. Likewise, authorization codes can be used to obtain a new access token, while verification codes are used as one-time codes included in email verification links.

  • /access/getAccessToken
  • /access/getAuthorizationCode
  • /access/getVerificationCode
  • /access/useVerificationCode

The /oauth endpoints

The /oauth endpoints are used to develop custom authentication and registration experiences that do not rely on the JavaScript SDK (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.

  • /oauth/auth_native
  • /oauth/auth_native_traditional
  • /oauth/forgot_password_native
  • /oauth/link_account_native
  • /oauth/register_native
  • /oauth/register_native_traditional
  • /oauth/token
  • /oauth/unlink_account_native
  • /oauth/update_profile_native
  • /oauth/verify_email_native

Accessing the Authentication API endpoints

The Authentication endpoints use the following URL syntax:

https://{app}.janraincapture.com/{endpoint}

To connect to your Authentication endpoints, replace {app} with your Capture domain name and replace {endpoint} with the desired endpoint. For example:

https://akamai-documentation.us-dev.janraincapture.com/access/getAccessToken

Authentication

The Access API endpoints

The Access API Endpoints require either Basic authentication or HMAC (Hash Message Authentication Code) authentication. To create a Basic authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take the newly created string and base64 encode it. For example, on a Mac, you can base encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

Or, if you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A=) should be used in your authentication header.

If you are making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password.

Alternatively, you can use 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.

To generate an HMAC 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 API client_secret.

  • Your API client ID.

After you have that information, complete the following procedure:

  1. Concatenate the endpoint, datetime, and sorted parameters with newline characters (\n). This creates the string you 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. For example:

Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=

The following Python script can be used to create an HMAC signature:

importhmac
frombase64 importb64encode
fromhashlib importsha1
defmake_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) fork, v inparams.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)}

The OAuth API endpoints

The OAuth API endpoints do not require authentication. However, you will typically need to include tokens or codes returned from the /access endpoints when making an OAuth call, and those endpoints do require authentication.

Resources

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

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Get an access token POST /access/getAccessToken{?uuid,type_name,for_client_id,id,key_attribute,key_value}
Get an authorization code POST /access/getAuthorizationCode{?uuid,type_name,for_client_id,redirect_uri,transaction_state,id,key_attribute,key_value,lifetime}
Get a verification code POST /access/getVerificationCode{?attribute_name,uuid,type_name,id,key_attribute,key_value,lifetime}
Use a verification code to set a timestamp POST /access/use_verification_code{?verification_code}
Complete social login POST /oauth/auth_native
Complete traditional login POST /oauth/auth_native_traditional
Send a reset password link POST /oauth/forgot_password_native
Link a social identity to a user account POST /oauth/link_account_native
Complete social registration POST /oauth/register_native
Complete traditional registration POST /oauth/register_native_traditional
Exchange an authorization code or refresh token for an access token POST /oauth/token{?grant_type,code,redirect_uri,refresh_token}
Unlink a social identity provider from a user account POST /oauth/unlink_account_native
Update a user profile POST /oauth/update_profile_native
Send a verify email address link POST /oauth/verify_email_native

Get an access token

This API call retrieves an access token for signing in to an application.

POST /access/getAccessToken{?uuid,type_name,for_client_id,id,key_attribute,key_value}

Sample: /access/getAccessToken?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&for_client_id=0987fghi0987fghi&id=999&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Required query parameters
for_client_id String 0987fghi0987fghi Client ID of the client whose access schema is being deleted.
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
id String 999 ID of the user record. Required unless you are using the uuid or key_attribute parameter.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.

Status 200 application/json

Object type: Response

Download schema: getAccessToken.json

Response body:

{
    "accessToken": "tc7blahblah3tmaz",
    "stat": "ok"
}

Sample curl request

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

Get an authorization code

Get an authorization code that can be exchanged for an access token and a refresh token.

POST /access/getAuthorizationCode{?uuid,type_name,for_client_id,redirect_uri,transaction_state,id,key_attribute,key_value,lifetime}

Sample: /access/getAuthorizationCode?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&for_client_id=0987fghi0987fghi&redirect_uri=http%3A//documentation.janraincapture.com/oauth&transaction_state=XXXXX&id=999&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com&lifetime=45

Parameter Type Sample Description
Required query parameters
for_client_id String 0987fghi0987fghi Client ID of the client whose access schema is being deleted.
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
id String 999 ID of the user record. Required unless you are using the uuid or key_attribute parameter.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lifetime String 45 Number of seconds for which the code is valid. The default is 30 seconds.
redirect_uri String http://documentation.janraincapture.com/oauth Token exchange URL.
transaction_state String XXXXX 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.

Status 200 application/json

Object type: Response

Download schema: getAuthorizationCode.json

Response body:

{
    "authorizationCode": "12345678912345",
    "stat": "ok"
}

Sample curl request

curl -G -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

Get a verification code

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.

POST /access/getVerificationCode{?attribute_name,uuid,type_name,id,key_attribute,key_value,lifetime}

Sample: /access/getVerificationCode?attribute_name=emailVerified&uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&id=999&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com&lifetime=45

Parameter Type Sample Description
Required query parameters
attribute_name String emailVerified Name of the attribute to be updated when using the verification code.
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
id String 999 ID of the user record. Required unless you are using the uuid or key_attribute parameter.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lifetime String 45 Number of seconds for which the code is valid. The default is 30 seconds.

Status 200 application/json

Object type: Response

Download schema: getVerificationCode.json

Response body:

{
    "verification_code": "htjwg2uphwz5mqxrnqe4tuvpxkzaqrr5",
    "stat": "ok"
}

Sample curl request

url -G -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

Use a verification code to set a timestamp

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.

POST /access/use_verification_code{?verification_code}

Sample: /access/use_verification_code?verification_code=12345678912345678912345678912345

Parameter Type Sample Description
Required query parameters
verification_code String 12345678912345678912345678912345 Verification code obtained in a prior call to the access/getVerificationCode endpoint.

Status 200 application/json

Object type: Response

Download schema: useVerificationCode.json

Response body:

{
    "argument_name": "verification_code",
    "request_id": "fvdfxwpxew2qe76p",
    "code": 200,
    "error_description": "verification code not recognized",
    "error": "invalid_argument",
    "stat": "error"
}

Sample curl request

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

Complete social login

Use this operation 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. This must be a POST request with all parameters included in the body of the request. They cannot be passed as URL parameters.

POST /oauth/auth_native

Content-Type: application/json

Object type: Request

Download schema: auth_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "registration_form": "socialRegistrationForm",
    "token": "mbaczwkyj63eyekm"
}

Status 100 application/json

Object type: Response

Download schema: 100.json

Response body:

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

Status 200 application/json

Object type: Response

Download schema: auth_native.json

Response body:

{
    "is_new": false,
    "stat": "ok",
    "access_token": "z0y98xv76u5t4rs3"
}

Status 310 application/json

Object type: Response

Download schema: 310.json

Response body:

{
    "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": ""
    }
}

Status 380 application/json

Object type: Response

Download schema: 380.json

Response body:

{
    "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_date_created": "2016-04-21 23:13:58.437196 +0000",
    "existing_photo": {
        "id": 10628,
        "value": "https://lh3.googleusercontent.com/fyd7jkgbnjLBX/AAAAAAAAAAI/AAAAAAAAAAA/hjsGTSDljl/photo.jpg?sz=400",
        "type": "other"
    }
}

Sample curl request

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'

Complete traditional login

Use this operation to complete traditional login using an email address or username along with a password.

POST /oauth/auth_native_traditional

Content-Type: application/json

Object type: Request

Download schema: auth_native_traditional-req.json

Request body:

{
    "client_id": "gct3q7xhcgfhfyy7cumgrte2k7d488uj",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "form": "signInForm",
    "signInEmailAddress": "karim.nafir@mail.com",
    "currentPassword": "p@ssw0rd"
}

Status 100 application/json

Object type: Response

Download schema: 100.json

Response body:

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

Status 200 application/json

Response body:

{
    "stat": "ok",
    "access_token": "z0y98xv76u5t4rs3"
}

Sample curl request

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'

Send a reset password link

Use this operation 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 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.

POST /oauth/forgot_password_native

Content-Type: application/json

Object type: Request

Download schema: forgot_password_native-req.json

Request body:

{
    "client_id": "12345 abcde12345abcde12345abcde12",
    "flow": "standard",
    "flow_version": "67890def-6789-defg-6789-67890defgh67",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "form": "forgotPasswordForm",
    "signInEmailAddress": "johndoe@example.com"
}

Status 100 application/json

Object type: Response

Download schema: 100.json

Response body:

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

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

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'

Link a social identity to a user account

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.

POST /oauth/link_account_native

Content-Type: application/json

Object type: Request

Download schema: link_account_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "token": "b5f21ac796fc5f2d76027a8b8c28366df1b8623c",
    "access_token": "bf7ffpmgh2pyh56r"
}

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

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'

Complete social registration

Use this operation to complete social registration.

POST /oauth/register_native

Content-Type: application/json

Object type: Request

Download schema: register_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "form": "registrationForm",
    "emailAddress": "karim.nafir@mail.com",
    "newPassword": "p@ssw0rd",
    "newPasswordConfirm": "p@ssw0rd",
    "lastName": "Nafir",
    "firstName": "Karim",
    "displayName": "Karim Nafir",
    "token": "bf7ffpmgh2pyh56r"
}

Status 200 application/json

Object type: Response

Download schema: register_native.json

Response body:

{
    "is_new": false,
    "stat": "ok",
    "access_token": "z0y98xv76u5t4rs3"
}

Sample curl request

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'\
    --data-urlencode 'birthdate[dateselect_year]=1930'\
    --data-urlencode 'birthdate[dateselect_month]=11'\
    --data-urlencode 'birthdate[dateselect_day]=3'\
    'https://my-app.janraincapture.com/oauth/register_native'

Complete traditional registration

Use this operation to complete traditional registration. Once complete, a user will be able to authenticate using an email address or username along with a password.

POST /oauth/register_native_traditional

Content-Type: application/json

Object type: Request

Download schema: register_native_traditional-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "form": "registrationForm",
    "emailAddress": "karim.nafir@mail.com",
    "newPassword": "p@ssw0rd",
    "newPasswordConfirm": "p@ssw0rd",
    "lastName": "Nafir",
    "firstName": "Karim",
    "displayName": "Karim Nafir"
}

Status 200 application/json

Object type: Response

Download schema: register_native_traditional.json

Response body:

{
    "stat": "ok",
    "access_token": "z0y98xv76u5t4rs3"
}

Sample curl request

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'\
    --data-urlencode 'birthdate[dateselect_year]=1930'\
    --data-urlencode 'birthdate[dateselect_month]=11'\
    --data-urlencode 'birthdate[dateselect_day]=3'\
   'https://my-app.janraincapture.com/oauth/register_native_traditional'

Exchange an authorization code or refresh token for an access token

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 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 for the length of your site or application’s session.

POST /oauth/token{?grant_type,code,redirect_uri,refresh_token}

Sample: /oauth/token?grant_type=authorization_code&code=7n12d0snfps1bb&redirect_uri=https%3A//documentation.akamai.com&refresh_token=bjkxc67m3nkva2bd982z

Parameter Type Sample Description
Required query parameters
code String 7n12d0snfps1bb 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.
grant_type Enumeration authorization_code Type of access grant you are passing into the call. If set to refresh_token, then you must supply the refresh_token parameter. If set to authorization_code, then you must supply the code parameter.
redirect_uri String https://documentation.akamai.com 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. Required only when the grant_type is set to authorization_code.
Optional query parameters
refresh_token String bjkxc67m3nkva2bd982z 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.

Status 200 application/json

Object type: Response

Download schema: token.json

Response body:

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

Sample curl requests

curl -G -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
curl -G -H "Authorization: Basic aW1fYV...NfbXk=" \
  --data-urlencode 'grant_type=refresh_token'\
  --data-urlencode 'refresh_token=bjkxc67m3nkva2bd982z'\
  https://my-app.janraincapture.com/oauth/token

Unlink a social identity provider from a user account

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.

POST /oauth/unlink_account_native

Content-Type: application/json

Object type: Request

Download schema: unlink_account_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "access_token": "bf7ffpmgh2pyh56r",
    "identifier_to_remove": "https://www.facebook.com/profile/1234567890"
}

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

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'

Update a user profile

Use this operation 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.

POST /oauth/update_profile_native

Content-Type: application/json

Object type: Request

Download schema: update_profile_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "form": "editProfileForm",
    "displayName": "Karim Nafir",
    "access_token": "w33g9cvu34m2e27s"
}

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl requests

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'
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'
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'
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 'birthdate[dateselect_year]=1930'\
    --data-urlencode 'birthdate[dateselect_month]=11'\
    --data-urlencode 'birthdate[dateselect_day]=3'\
    --data-urlencode 'access_token=z0y98xv76u5t4rs3'\
    'https://my-app.janraincapture.com/oauth/update_profile_native'

Send a verify email address link

Use this operation 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 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.

POST /oauth/verify_email_native

Content-Type: application/json

Object type: Request

Download schema: verify_email_native-req.json

Request body:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "form": "resendVerificationForm",
    "signInEmailAddress": "karim.nafir@mail.com"
}

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

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'

Data

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

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Request

Completes social registration. To make this call, you first make a call to oauth/auth_native.

Download schema: register_native-req.json, register_native_traditional-req.json, auth_native-req.json, auth_native_traditional-req.json, forgot_password_native-req.json, link_account_native-req.json, unlink_account_native-req.json, update_profile_native-req.json, verify_email_native-req.json

Sample POST request:

{
    "client_id": "xyv3q7xhces2yy7cumgrte24epx4m2st",
    "flow": "standard",
    "flow_version": "20180118163311891913",
    "locale": "en-US",
    "redirect_uri": "http://localhost",
    "response_type": "token",
    "registration_form": "socialRegistrationForm",
    "token": "mbaczwkyj63eyekm"
}

Request members

Member Type Required Description
Request: Completes social registration. To make this call, you first make a call to oauth/auth_native.
access_token String Registration access token returned after authentication or registration with a previous call (/oauth/auth_native, /oauth/auth_native_traditional, and so on) if the response_type parameter was set to token. If the response_type was set to code, you must exchange the authorization code for an access token using the /oauth/token call.
client_id String 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.
currentPassword String Password of the user logging on.
displayName String Display name of the user.
emailAddress String Email address of the user. Corresponds to the email attribute.
firstName String First name of the user. Corresponds to the givenName attribute.
flow String Name of the flow configured with the social registration experience you want to use.
flow_version String 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. Instead, you must specify the version number if you want to use the most recent version.
form String Name of the form to be used to for social registration. This parameter determines the field names that must be included when submitting this API call.
identifier_to_remove String 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 forprofiles.identifier.
lastName String Last name of the user. Corresponds to the familyName attribute.
locale String Code for the language you want to use for the registration experience. This parameter determines the language for any error messages returned to you and any registration confirmation emails sent to users, and corresponds to the janrain.settings.language JavaScript setting used in widget-based implementations.
newPassword String User’s password.
newPasswordConfirm String User’s password. This value must match the value of the newPassword parameter.
redirect_uri String Required for legacy purposes and is not used for any functionality in this call. The parameter value must begin with http: or https: and we recommend that this match the URL and protocol of your website.
registration_form String Name of the form used for social registration. This parameter determines what is included in the error response if no existing record can be found what uses the same email address as the one returned by the social provider after a successful authentication. When set, the response will include values for prereg_fields, which includes data from the social provider’s payload mapped to fields in your social registration form. You can use this data to pre-populate the parameters for the oauth/register_native.
response_type Enumeration 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.
signInEmailAddress Enumeration Email address of the user who has forgotten his or her password.
token String 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 configured for the API client used to make this call. This can be configured in the Default Settings for your Registration application if you have a single Social Login application. The token will be a unique 40-character string and can be used with the auth_info endpoint to retrieve a user’s social profile directly. However, this is typically not necessary when using the oauth endpoints for registration, because that data is automatically retrieved and stored for you.

Response

Retrieves an access token for signing in to an application.

Download schema: getAccessToken.json, getAuthorizationCode.json, getVerificationCode.json, useVerificationCode.json, 100.json, register_native.json, register_native_traditional.json, 310.json, 380.json, auth_native.json, token.json, auth_native_traditional.json

Sample POST response:

{
    "argument_name": "verification_code",
    "request_id": "fvdfxwpxew2qe76p",
    "code": 200,
    "error_description": "verification code not recognized",
    "error": "invalid_argument",
    "stat": "error"
}

Response members

Member Type Description
Response: Retrieves an access token for signing in to an application.
access_token String Unique identifier of the access token returned after a successful registration.
accessToken String Unique identifier of the returned access token.
argument_name String General category assigned to the error.
authorizationCode String Unique identifier of the returned authorization code.
code Integer Integer code assigned to the error.
error String Title assigned to the error.
error_description String Brief description of the error.
existing_date_created String Date and time that the user’s account was created on the social login provider.
existing_display_name String User’s display.
existing_photo Response.existing_photo Collection of user photos maintained by the social login provider.
existing_provider String Unique identifier of the social login provider.
expires_in Integer Amount of time, in seconds, before the access token expires.
is_new Boolean When new, indicates that the social login account is for a new, previously unregistered user.
prereg_fields Response.prereg_fields User account properties and property values returned from the social login provider.
refresh_token String Unique identifier of the refresh token returned along with the access token. Before an access token expires, you can use a refresh token to obtain a new access token.
request_id String Unique identifier of the API call responsible for the error.
stat Enumeration Indicates the status of the current operation, either ok, error, or fail.
verification_code String Unique identifier of the returned verification code.
Response.existing_photo: Collection of user photos maintained by the social login provider.
id Integer Unique identifier of the user’s photo.
type String Photo type.
value String URL to the user’s photo.
Response.prereg_fields: User account properties and property values returned from the social login provider.
addressCity String, Null User’s home city.
addressCountry String User’s country of residence.
addressPostalCode String, Null User’s zip/postal code.
addressState String User’s home state.
addressStreetAddress1 String, Null User’s home address (line 1).
addressStreetAddress2 String, Null User’s home address (line 2).
birthdate String, Null User’s date of birth.
displayName String User’s display name.
emailAddress String User’s email address.
firstName String User’s first name.
gender String User’s gender.
lastName String User’s last name.
middleName String, Null User’s middle name.
mobile String, Null User’s mobile phone number.
optInRegistration Boolean When true, indicates that the user has agreed to the terms of service and reviewed the privacy policy.
phone String, Null User’s home phone number.

Errors

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

Error responses

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

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

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

  • Invalid form
  • Invalid refresh token
  • Invalid social login token
  • No such form

Note, too that the stat property indicates that the API call failed. If your API call succeeds, you’ll get a similar response. However, a success response will not have an err section and the stat will be set to ok: { "stat": "ok" } Authentication API error responses are summarized in the following table:

Code Description
100 A required parameter is missing.
200 Invalid form: the form is not valid for the flow indicated in the call.
200 The refresh token is invalid or has expired.
200 The social login token is invalid or has expired.
200 No such form: the form specified in the flow is not a valid form name.
210 The email address does not exist.
210 Invalid credentials: the value entered as the user’s current password is not correct.
212 The supplied email address has not been registered. No forgot password email can be sent..
310 User not registered: neither the social identity nor the email address returned by the provider are registered.
361 The social identity is already associated with a user account.
380 Email address already registered. 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.
390 Field validation error. This can also indicate that a required field is missing or that a unique value has already been used.
402 The supplied API client credentials cannot be used for registration.
413 The access token is invalid or has expired.
413 The authorization code is invalid or has expired.
420 The redirect URI in the oauth/token call does not match the redirect URI specified when the authorized code was returned.
500 Invalid flow value: either the flow name, version, or locale is not correct.
540 Too many requests. Service is temporarily unavailable.
540 The submitted email address is for an account that has no password. No forgot password email can be sent.

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


Last modified: 8/28/2019