Access Tokens
- Former user (Deleted)
- Persia Xenopoulou (Deactivated)
- p_demou (Deactivated)
- Former user (Deleted)
On this page
Overview
Access tokens are used to identify and authenticate customers accessing CRM.COM from third-party systems, such as mobile applications or portals.
Major features
- Access tokens identify and authenticate users through a code, such as a telephone number, or a combination of an identifier and passcode, such as a username and a four-digit PIN.
- Lost or forgotten passcodes can be reset and forwarded to customers through email or SMS.
- Access tokens can be created automatically by the system or manually through the UI or Web API.
- The activation of access tokens may require verification. Verification codes can be communicated to customers through email or SMS.
- A one-time password (OTP) can be used to grant single-session access.
Setting Up Access Tokens
Classifications
Classifications are used to define the operational characteristics of access tokens. Besides the rules set in the business definition, rules can be applied to each classification regarding the automatic creation and deletion of tokens and the formatting of credentials.
If a classification is not specified when a token is created, then the settings defined in the active access token definition are applied.
Classification fields
The table describes the sections of the Access Token Classifications Data Entry page and explains how the fields on the page are used.
Mandatory
Configurable
Settings (Information on generating and formatting credentials) | |
|---|---|
| Identifier |
If None is selected, then the Format field becomes available, with the following options:
Minimum Length: The number of alphabetical (a-z), numerical (0-9) or special characters required for the identifier. If the Format is set to 'Free Text' or 'Email Address', the minimum number of alphabetical characters and other special characters can also be specified. |
| Passcode |
If None is selected, then the Minimum Length and the minimum number of alphabetical (a-z), numerical (0-9) or special characters required for the passcode can be defined. When the Automatic Creation Method of passcodes is set to None (i.e. not generated automatically), only super users can manually set passcodes when creating or editing tokens (regular users cannot). The passcode will be automatically generated using the format restrictions set here (in case of regular users) |
| Authentication Code |
If None is selected, then the Format field becomes available, with the following options:
Minimum Length: The number of alphabetical (a-z), numerical (0-9) or special characters required for the authentication code. If the Format is set to 'Free Text' or 'Email Address', the minimum number of alphabetical characters and other special characters can also be specified. |
Automation | Allow Creating Access Tokens with No Identifier and Passcode Set Access Tokens as 'Not Effective' on Removing the Last Entity Association (rewards participant or accounts receivable) Delete Access Tokens on Removing the Last Entity Association (rewards participant or accounts receivable) |
| OTP | Select whether customers can gain access to their CRM.COM data using a one-time password (OTP) instead of an authentication code, or an identifier and passcode. An OTP is valid for only one login session or transaction, on one device. If an OTP is supported then its Validity Period must be defined in seconds. |
| Invalid Authentication Policy | Define the policy for handling invalid customer authentication attempts.
The Invalid Authentication Policy is applied when the access token is used, using a combination of the Identifier and Pass Code (and not the Authentication Code). |
Business definitions
Definitions are used to regulate the creation of access tokens, as well as to establishing policies that control the format of user credentials. It is possible to define whether access tokens can be created without an identifier and passcode or if tokens get deactivated when their last entity association (rewards participant or accounts receivable) is removed. Definition settings are overridden if a classification that has its own settings is defined on an access token.
Definition fields
The table describes the sections of the Access Token Definitions Data Entry page and explains how the fields in the page are used.
Mandatory
Configurable
Settings For Access Tokens With No Classification (Information on generating and formatting credentials) | |
|---|---|
| Identifier |
If None is selected, then the Format field becomes available, with the following options:
Minimum Length: The number of alphabetical (a-z), numerical (0-9) or special characters required for the identifier. If the Format is set to 'Free Text' or 'Email Address', the minimum number of alphabetical characters and other special characters can also be specified. |
| Passcode |
If None is selected, then the Minimum Length and the minimum number of alphabetical (a-z), numerical (0-9) or special characters required for the passcode can be defined. When the Automatic Creation Method of passcodes is set to None (i.e. not generated automatically), only super users can manually set passcodes when creating or editing tokens (regular users cannot). The passcode will be automatically generated using the format restrictions set here (in case of regular users) |
| Authentication Code |
If None is selected, then the Format field becomes available, with the following options:
Minimum Length: The number of alphabetical (a-z), numerical (0-9) or special characters required for the authentication code. If the Format is set to 'Free Text' or 'Email Address', the minimum number of alphabetical characters and other special characters can also be specified. |
Automation | Allow Creating Access Tokens with No Identifier and Passcode Set Access Tokens as 'Not Effective' on Removing the Last Entity Association (e.g., rewards participant or accounts receivable) Delete Access Tokens on Removing the Last Entity Association (e.g., rewards participant or accounts receivable) |
Global Settings (Settings defining the association of access tokens with accounts receivables and rewards participants) | |
| Accounts Receivable | Allow Creating Access Tokens on Creating Accounts Receivable Always Require at Least One Access Token (per account) Maximum Number of Access Tokens (that can be related to each accounts receivable) Require Verification (of auto-generated access tokens when creating a new accounts receivable). Tokens will be generated in a 'Pending Verification' life cycle state. The verification code will also be auto-generated. Require Verification of Access Tokens per Access Token Classification: Available only if 'Require Verification' is enabled. If a classification is not selected, then verification will be applied to all access tokens. Required Number of Access Tokens per Access Token Classification: Determines the minimum and maximum number of tokens for each classification that can be associated with an accounts receivable |
| Rewards Participants | Allow Creating Access Tokens on Creating Rewards Participant Always Require at Least One Access Token (per participant) Maximum Number of Access Tokens (that can be related to each rewards participant) Require Verification (of auto-generated access tokens when creating a new rewards participant). Tokens will be generated in a 'Pending Verification' life cycle state. The verification code will also be auto-generated. Require Verification of Access Tokens per Access Token Classification: Available only if 'Require Verification' is enabled. If a classification is not selected, then verification will be applied to all access tokens. Required Number of Access Tokens per Access Token Classification: Determines the minimum and maximum number of tokens for each classification that can be associated with a rewards participant. |
| Automation | Specify automation settings associated with the creation and update of access tokens, based on specified email addresses or phone numbers. Enable Allow Creating and Updating Access Tokens Based on Email Address and/or Allow Creating and Updating Access Tokens Based on Phone Number to automatically generate tokens for each email and phone number of an accounts receivable or a rewards participant when creating or updating tokens. Automatic Application: For each option above select between, 'Authentication Code', 'Identifier' or 'Both' to define the use of the email or phone number. Select a Classification to apply on automatically generated access tokens. If the 'Automatic Creation Method' of the identifier or authentication code of the selected classification or of the definition (if no classification is selected) is set to 'None' then access tokens will not be created. |
| Invalid Authentication Policy | Define the policy for handling invalid customer authentication attempts.
The Invalid Authentication Policy is applied when the access token is used, using a combination of the Identifier and Pass Code (and not the Authentication Code). |
Related configuration areas
The following modules are related to access tokens and may be configured for the access tokens module to operate at its full capacity.
| Module Link | Area | Description |
|---|---|---|
Communication Templates | Configure templates including access token tags, to be forwarded by email or SMS when an access token is related to an accounts receivable or a rewards participant. | |
| Communications | Queue External Systems | Configure an external system to handle communications, if communications are not handled directly (and sent by email or SMS) from CRM.COM, |
| Communications | Event-based Communication Definition | Configure specific events that trigger communications. E.g., a new passcode request from a customer will result in an email. |
Using Access Tokens
Foundation > Access Tokens > Manage Access Tokens
Access token fields
The table describes the sections of the Access Token Data Entry page and explains how the fields on the page are used.
Mandatory
Configurable
Main Information (Access token details) | |
|---|---|
Authentication Code, Identifier and Passcode are either 'read-only' or must follow a specific format as defined in the Authentication Code: A code used by customers to gain access to the system and to their personal data (instead of an identifier and passcode) Identifier: A string of characters used to identify the customer (username). Passcode: A code used to authenticate the identifier.
Rewards Participant: The participant linked with the specific token and which can be edited only while creating a token. Accounts Receivable: The account linked with the specific access token and which can be edited only while creating a token. The association between an account and an access token can be canceled by removing the token from the accounts receivable Data Entry page. If an accounts receivable is specified, a rewards participant must be associated with the account to be available for selection. Similarly, if a rewards participant is specified, an accounts receivable must be associated with the participant to be available for selection. The Life Cycle State of an access token can be 'Effective', 'Not Effective' or 'Pending Verification'. Only 'Effective' tokens are operational and can be used to access the system. A verification code is necessary to verify a token that is 'Pending Verification'. | |
Log Information (related to the verification of the access token) | |
|
Creating and processing access tokens
Validations take place before an action is initiated (prerequisite) or after it is submitted (postcondition).
Selecting and creating an access token
Selecting
Specify the criteria that match the access token you are interested in (e.g., life cycle state and classification) and press SEARCH. Select the desired token by its number to access the Data Entry page for more information.
Creating
Access tokens can be created manually through the access token Data Entry page or automatically when a rewards participant or accounts receivable is created. Tokens can also be created manually from either of the two modules (rewards participant or accounts receivable) if the system is not configured to do so automatically.
Manually
Click on NEW from the Actions menu to create a new token. Provide the information that is defined as mandatory in the fields table and SAVE the token.
When creating an access token, the user account or participant must be defined, unless:
- The user creating the token is a super user and the Automatic Creation Method of the passcode is set to 'None'.
- The Allow Creating Access Tokens with No Identifier and Pass Code is selected at the definition.
Automatically (when an account or rewards participant is created)
In the active access token definition, select the option 'Allow Creating Access Tokens on Creating Accounts Receivable' (or Rewards Participants) and provide the required information for the generation of the authentication code, identifier and passcode.
It is also possible to automatically generate an access token for all email addresses and/or phone number defined for a rewards participant or accounts receivable. To do this, create or update an account or participant with a defined email address or phone number. The email or phone number will be used as the authentication code or identifier of the access tokens, depending on the set up in the Automation settings of the access token definition.
The access token definition setting Allow Creating and Updating Access Tokens Based on Email Address/Phone Number must be 'enabled'.
If the Automatic Creation Method of the identifier or authentication code of the selected classification (or of the definition where no classification is selected) is set to 'None', access tokens cannot be created using email or phone numbers.
Refer to the access token definition for more information.
Modifying an access token
Use EDIT from the Actions menu to enter edit mode. If the settings in the access token definition or classification for the authentication code, identifier or passcode, are based on an auto-generated value, they cannot be edited.
Rewards participants or accounts receivables cannot be edited once set (in the access token Data Entry page). Access tokens associated with a rewards participant or accounts receivable can be modified from each entity's Access Tokens section.
Deleting an access token
Access tokens that are no longer required can be deleted. This can be done manually, by using DELETE from the Data Entry page Actions menu.
If 'Delete Access Tokens on Removing the Last Entity Association' in the Automation Settings of the access token definition is enabled, tokens are automatically deleted when:
- Removing an access token from an accounts receivable or rewards participant
- Terminating an accounts receivable or rewards participant
Additional Information
Prerequisites | The life cycle state of the access token must be 'Not Effective'. The access token is not associated with a rewards participant or accounts receivable. |
|---|
Updating the life cycle state of an access token
The life cycle state of an access token can be set to 'Effective' or 'Not effective'. An 'Effective' token indicates it can be used by customers to authenticate themselves in CRM.COM. The life cycle state can be toggled by the user from the Actions menu and can be updated by the system when:
- An access token in a 'Pending Verification' state is verified.
- An access token is removed from an accounts receivable or rewards participant OR an accounts receivable or rewards participant is terminated (provided 'Set Access Tokens as Not Effective on Removing the Last Entity Association' is enabled in the Automation Settings of the /wiki/spaces/WIP/pages/10010278).
Additional Information
| Set as not Effective | Set as Effective | |
|---|---|---|
Prerequisites | The life cycle state of the access token must be 'Effective'. | The life cycle state of the access token must be 'Not Effective'. |
| Postconditions | The access token is not associated with any reward participants or accounts receivable. | Not applicable |
Verifying an access token
Access tokens can be configured to require verification before customers activate them for use.
The verification process takes place when:
- new access tokens are created through the rewards participant or accounts receivable page
- an existing access token is associated with a rewards participant or accounts receivable.
Tokens are verified using a code sent by the system (by email, SMS, or mobile app) to the customer. If the code is lost, it can be requested by the customer and resent by the system.
An access token is in a 'Pending Verification' life cycle state until it is verified. Once verified, its state becomes 'Effective', the token is activated and it can be used by the customer for login.
To configure the system to support the verification process:
- Enable 'Require Verification' in the access token definition.
- Create a communication template including an access token verification code tag that will be replaced with the verification code generated by the system.
- Set up event-based communication definitions to send an email or SMS using the communication template each time an access token is associated with a rewards participant or accounts receivable by enabling one of the following events:
- On Resetting Verification Code of a Rewards Participant Access Token
- On Resetting Verification Code of an Accounts Receivable Access Token
- On Creating an Access Token that Requires Verification
Resetting a passcode
Passcodes are similar to passwords. Lost user passcodes can be reset automatically and replaced with an auto-generated passcode, or manually (complying with the formatting regulations set in the active access token definition or classification). Reset passcodes can be sent to the customers by email or SMS.
To reset a passcode to an auto-generated string and communicate with the customer:
- Click on Reset Passcode from the Data Entry page Actions menu to generate a new code.
- Create a communication template including the access token passcode tag that will be replaced with the passcode generated by the system or provided by the user.
- Set up event-based communication definitions to send an email or SMS using the communication template whenever a passcode is reset on an access token. Enable 'On Resetting Pass Code of a Rewards Participant Access Token' or 'On Resetting Pass Code of an Accounts Receivable Access Token'.
To manually reset the passcode, EDIT the access token and update it (instead of using the Reset Passcode action).
Additional Information
| Action | Manual reset | Automatic reset |
|---|---|---|
Prerequisites | The life cycle state of the access token must be 'Effective'. The user making the update must be a super user. The Automatic Creation Method of the passcode in the definition or classification must be set to 'None'. | The life cycle state of the access token must be 'Effective'. |
| Postconditions | The passcode must comply with the formatting rules specified in the access token definition or classification. | Not applicable |
Handling invalid login attempts
To protect against unauthorized access, a customer can be locked out after multiple consecutive invalid login attempts.
It is possible to define the maximum number of failed attempts allowed within a specified period. If the number is reached, customer access to the system is denied for the duration of a configurable lockout period. The customer is allowed to log in again when the lockout period ends or is canceled by a super user.
Canceling the lockout period
Super users can reset user access by canceling the lockout period.
- Navigate to Manage Users and go to the user's Data Entry page.
- From the Actions menu, click Cancel Lock-out Period.
Applying business flows on access tokens
Removing an assigned token from a participant or account
The association between an access token and accounts receivable or rewards participant can be canceled by removing the token from the entity's Data Entry page.
- Access the Data Entry page of the account or participant whose association with the token should be canceled.
- Enter EDIT mode from the Top Menu and click on the 'Access Tokens' tab.
- Select the unwanted access token.
- Click REMOVE and SAVE.
- Assigned access tokens cannot be deleted or set as 'Not Effective' as long as they are associated with a rewards participant or accounts receivable.
- The account or participant cannot be updated through the access token Data Entry page.
Communicating an access token
Communicating token credentials can be crucial. Customers use access tokens primarily to gain access to CRM.COM, through portals or mobile apps. The process of generating and communicating tokens is automated.
When a new customer is registered through an external system, an access token and its details are communicated to the customer.
Set up event-based communication definitions to automatically email or SMS customers when specific events associated with access tokens occur. The following events are available:
- Assigning an access token to a rewards participant or accounts receivable
- Auto-generating a passcode of a rewards participant or an account receivable access token
- Resetting the passcode of an access token of a rewards participant or accounts receivable
- Resetting the verification of an access token of a rewards participant or accounts receivable
- Creating an Access Token that requires verification
Communication templates including access token tags (text to be replaced with values specific to the token) can be used in the definition and sent to the customer when the event occurs.
Manual communications (including tags) can also be created and sent from the communications Data Entry page. Tags related to actions can be used as long as the access token is listed in the 'Referring To' entities. Tags can be selected by typing '#'.
Refer to the Communications manual for a comprehensive list of access tokens tags.
Access Token Business Examples
Creating and Verifying an Access Token
Scenario
Company ZX has created a mobile app for customers participating in its loyalty scheme. Customers can register through the app by using their email address. Once registered, the customers receive a verification code that they must provide through the app, to log in and gain access to the system.
Solution
The mobile app must be integrated with CRM.COM using the available CRM.COM WEB APIs.
Configuration
CRM.COM must be configured as follows:
Communication template
A communication template should be set up to communicate with the customer whenever an access token is related to a rewards participant. The communication template media should be set to 'Email' so that when the communication is created, verification codes are delivered to the customer's inbox.
Dear #accounts_receivable.name
Welcome to our family!
Please use the following code to activate your account: #access_token.verification_code
Once the account is activated please use the following information to access your personal account.
Access Token Number: #access_token.number
Access Token Identifier: #access_token.identifier
Access Token Passcode: #access_token.pass_code
Access token definition
Set up the definition as follows:
- Identifier: format email address
- Passcode: define the required restriction
- Automation: Select 'Allow Creating Access Tokens with No Identifier and Passcode'
- Rewards Participant: Select 'Require Verification'
Event-based communication definition
Configuration > CRM Application > Communications > Set Up Event-based Communication Definition
- Select 'Apply on Assigning Access Tokens to Rewards Participant'
- Select the created communication template that includes the #access_token.verification_code tag (to be replaced by the generated verification code).
Using the verification code
When a new customer registers through the mobile app, CRM.COM will:
- Create an access token in a 'Pending Verification' life cycle state.
- Generate a verification code and send it to the customer.
Once the customer enters the verification code using the mobile app, the life cycle state of the access token will change to 'Effective', prompting the customer to log into the mobile app using the new account.
Notes
- If you are using a previous release, view CRM.COM Release Changes.
- Use the WEB API to create and manage access tokens from an external system, such as a customer portal. Refer to the Access Tokens WEB API for a comprehensive list of available actions.
Glossary
| CRM.COM Term | Description |
|---|---|
| One-time password (OTP) | A password that is valid for only one login session or transaction, on a computer system or other digital device. In CRM.COM, OTPs are used to authenticate access tokens and identify accounts receivables or rewards participants. |
| Communications | Log the interaction between customers and agents. Communications can support multiple communication media such as email, SMS, telephony, post, and others. |
| Accounts Receivable | A ledger of the financial transactions carried out between a company and its customers, such as invoices and payments. |
| Rewards Participant | A customer who is participating in a rewards program and can be awarded offers provided through the program. |