Authentication

Scopes & Capabilities

Scopes indicate the potential actions for which a token may be used.
Capabilities indicate the actions that a token is capable of doing.

If a permission is listed inside of scopes and not inside of capabilities, then some further action must be taken. See the table below to understand how to get each capability.

Scope	Definition
`UPDATE_PROFILE`	Allows the update of the profile of the access token. The primary use to set the email address of the token to associate it with an profile at Extole. This scope is always capable.
`SHARE_EMAIL`	Allows sharing through Email. This scope is capable once the profile has been updated with an email address so the token is no longer anonymous.
`SHARE_FACEBOOK`	Allows sharing through Facebook. This scope is capable once a Facebook Token has been received.
`SHARE_TWITTER`	Allows sharing through Twitter. This scope is capable once a Twitter token has been received.
`VIEW_DASHBOARD`	Allows the token to retrieve the advocate dashboard. This scope is capable with an authenticated token that has gone through an email authentication flow.
`REWARDABLE`	Allows the token to check for valid rewards. This scope is capable with an authenticated token that has gone through an email authentication flow.

Example

When an anonymous token is first created, the only capability available is UPDATE_PROFILE. The token may not be used for any other activity. Once the Update Profile endpoint is used to set a user to the token, the token will gain the capability to share via email.

GET /v4/token

Response:
{
    "access_token": "DI3ZCZ97V3V1F9SUA9T",
    "expires_in": 2592000,
    "scopes": [
        "UPDATE_PROFILE",
        "SHARE_EMAIL",
        "SHARE_FACEBOOK",
        "SHARE_TWITTER",
        "REWARDABLE",
        "VIEW_DASHBOARD"
    ],
    "capabilities": [
        "UPDATE_PROFILE"
    ]
}

POST /v4/me
{
    "access_token": "DI3ZCZ97V3V1F9SUA9T",
    "email": "[email protected]",
    "first_name": "Matthew",
    "last_name": "James"
}

Response:
{
    "status": "success"
}

GET /v4/token/DI3ZCZ97V3V1F9SUA9T
{
    "access_token": "DI3ZCZ97V3V1F9SUA9T",
    "expires_in": 2592000,
    "scopes": [
        "UPDATE_PROFILE",
        "SHARE_EMAIL",
        "SHARE_FACEBOOK",
        "SHARE_TWITTER",
        "REWARDABLE",
        "VIEW_DASHBOARD"
    ],
    "capabilities": [
        "UPDATE_PROFILE",
        "SHARE_EMAIL",
        "REWARDABLE"
    ]
}

Verifying Consumers

Extole is designed to allow anyone to be able to share and participate in your programs with as little registration or verification as possible. In terms of a Refer A Friend program, this means that the advocate should not need to log in, register, or "prove" their identity in any way to be able to share. Our simple public model makes using Extole extremely simple to setup.

Levels of Verification

A consumer has three verification levels with Extole:

Anonymous: An anonymous consumer has an access token that is tied to their device (typically via cookie). This person has no email address or partner_user_id associated with their token. Typically, these people can see basic Extole creative content, but cannot take actions such as sharing.
Identified: Once a consumer is identified, typically by an email address, they are able to get a Share Link and share through Extole. The Extole security model takes into account that it's easy for a person to enter someone else's email address. This person has access to session information, but does not have access to any PII or other private information.
Verified: This consumer has proven their identity. Once their identity is verified, this person has access to all information associated with themselves, such as historical shares and rewards.

When an consumer is attempting to review information they may have entered in a previous session or details that have been added from the program they participated in (such as who they have emailed, what rewards they have earned, etc.), they must be able to verify their identity.

Methods of Verification

Extole supports three methods of verifying a consumer's identity:

Email Verification: In this method, Extole will email the consumer with a link that has an authentication token. When the consumer clicks on this link and returns to the Extole program experience, they become verified as the owner of the email and can view any history associated with that email address.
JSON Web Token (JWT): In this SSO method, you responsible for verifying the identity of your consumers (typically via login). After you verify someone, a secure SSO token is sent to Extole through a web request or API that has been digitally signed by a shared key (or PKI). We are then able to validate the signature of the token and know your business has authenticated the consumer. You can create JWTs directly in the Extole platform.
Explicit Authorization (Resource Owner Credential Grant): In this OAuth pattern, the Extole Authenticated API may be used to mark a token as verified. This method allows a consumer behind login to see their stats.