Symantec VIP Web Services Developer's Guide


Table of Contents

Overview................................................................................................................................................9Getting started....................................................................................................................................10

Getting started................................................................................................................................................................ 10Supported environments............................................................................................................................................... 10Obtaining your VIP certificate.......................................................................................................................................10Testing your secure connection to VIP web services............................................................................................... 11Using Java to test your configuration.........................................................................................................................11Using .NET to test your configuration.........................................................................................................................14

VIP Service credential management APIs.......................................................................................17Credential states.............................................................................................................................................................17Credential management API overview.........................................................................................................................18Activating and deactivating credentials...................................................................................................................... 19

Activating credentials................................................................................................................................................ 20Activation request...............................................................................................................................................20Activation response............................................................................................................................................21

Deactivating credentials............................................................................................................................................ 22Deactivation request.......................................................................................................................................... 22Deactivation response........................................................................................................................................23DeactivateToken error codes............................................................................................................................. 23

Validating credentials.....................................................................................................................................................24Validate...................................................................................................................................................................... 24

Validation request...............................................................................................................................................24Validation response............................................................................................................................................25Validation error codes........................................................................................................................................ 26

Validating multiple credentials...................................................................................................................................26Validation request for multiple credentials........................................................................................................26Validation response for multiple credentials.....................................................................................................27ValidateMultiple error codes.............................................................................................................................. 28

Validating challenge/response (CR) requests...........................................................................................................29ValidateCR request............................................................................................................................................ 29ValidateCR response......................................................................................................................................... 30ValidationCR error codes...................................................................................................................................31

Synchronizing credentials.............................................................................................................................................32Synchronization request............................................................................................................................................32

Sample Synchronize SOAP XML request.........................................................................................................33Synchronization response......................................................................................................................................... 33

2


Sample Synchronize SOAP XML response...................................................................................................... 33Synchronize error codes........................................................................................................................................... 34

Unlocking credentials.................................................................................................................................................... 34Unlock request.......................................................................................................................................................... 34

Sample UnlockToken SOAP XML request........................................................................................................ 35Unlock response........................................................................................................................................................35

Sample UnlockToken SOAP XML response..................................................................................................... 35UnlockToken error codes.......................................................................................................................................... 36

Disabling credentials..................................................................................................................................................... 36Disabling credentials................................................................................................................................................. 36

Disable request.................................................................................................................................................. 37Disable response............................................................................................................................................... 37DisableToken error codes.................................................................................................................................. 38

Enabling credentials...................................................................................................................................................... 38Enable request.........................................................................................................................................................39

Sample EnableToken SOAP XML request........................................................................................................39Enable request.........................................................................................................................................................39

Sample EnableToken SOAP XML request........................................................................................................40EnableToken error codes.......................................................................................................................................... 40

Setting and managing temporary security codes...................................................................................................... 40Setting a temporary security code............................................................................................................................41

SetTemporaryPassword request.......................................................................................................................41SetTemporaryPassword response....................................................................................................................42SetTemporaryPassword error codes................................................................................................................. 43

Generating a temporary security code..................................................................................................................... 43GenerateTemporaryPassword request............................................................................................................. 44GenerateTemporaryPassword response.......................................................................................................... 44GenerateTemporaryPassword error codes........................................................................................................45

Setting temporary security code expiration dates.................................................................................................... 46SetTemporaryPwdExpiration request............................................................................................................... 46SetTemporaryPwdExpiration response.............................................................................................................46SetTemporaryPwdExpiration error codes.......................................................................................................... 47

Getting temporary security code expiration dates....................................................................................................48GetTemporaryPwdExpiration request............................................................................................................... 48GetTemporaryPwdExpiration response............................................................................................................ 48GetTemporaryPwdExpiration error codes..........................................................................................................49

Sending a temporary security code for SMS OTP...................................................................................................50Checking security codes on locked credentials........................................................................................................ 50

Request for checking a security code on a locked credential..................................................................................50Sample CheckOTP SOAP XML request........................................................................................................... 51

3


Response for checking a security code on a locked credential...............................................................................51Sample CheckOTP SOAP XML response........................................................................................................ 52

CheckOTP error codes............................................................................................................................................. 52Getting information about a credential........................................................................................................................53

Request for getting information about a credential.................................................................................................. 53Sample getTokenInformation SOAP XML request............................................................................................ 54

Response for getting information about a credential................................................................................................54Sample getTokenInformation SOAP XML response......................................................................................... 55

getTokenInformation error codes.............................................................................................................................. 56Performing operations on behalf of others.................................................................................................................56

Request using the AuthorizerAccountId element..................................................................................................... 57Response to request using the AuthorizerAccountId element.......................................................................... 57

Using Network Intelligence........................................................................................................................................... 58Reason codes for a disabled and deactivated credential........................................................................................ 58Global failed count.................................................................................................................................................... 58Network Intelligence APIs......................................................................................................................................... 59

Validate for Network Intelligence....................................................................................................................... 59Get Token Information with Network Intelligence.............................................................................................. 60

SMS OTP credential APIs................................................................................................................. 61Registering an SMS OTP credential............................................................................................................................ 61Using the SMS credential..............................................................................................................................................61SMS OTP credential APIs..............................................................................................................................................62

Registering an SMS OTP credential........................................................................................................................ 62Sample register for SMS OTP request............................................................................................................. 62Sample Register for SMS OTP response......................................................................................................... 63Register error codes.......................................................................................................................................... 64

Activating an SMS OTP credential........................................................................................................................... 64Sample ActivateToken for SMS OTP request................................................................................................... 65Sample ActivateToken for SMS OTP response................................................................................................ 65ActivateToken for SMS OTP error codes.......................................................................................................... 66

SendOTP for SMS OTP........................................................................................................................................... 67Sample SendOTP for SMS OTP request..........................................................................................................67Sample SendOTP for SMS OTP response.......................................................................................................68SendOTP for SMS OTP error codes.................................................................................................................68

Validate for SMS OTP...............................................................................................................................................69Validate for SMS OTP request.......................................................................................................................... 69Validate for SMS OTP response....................................................................................................................... 70Validate for SMS OTP error codes....................................................................................................................71

Additional SMS OTP APIs............................................................................................................................................. 71DeactivateToken for SMS OTP.................................................................................................................................72

4


Sample DeactivateToken for SMS OTP request............................................................................................... 72DeactivateToken for SMS OTP response..........................................................................................................73DeactivateToken for SMS OTP error codes......................................................................................................73

EnableToken for SMS OTP...................................................................................................................................... 74EnableToken for SMS OTP request.................................................................................................................. 74EnableToken for SMS OTP response............................................................................................................... 75EnableToken for SMS OTP error codes............................................................................................................75

DisableToken for SMS OTP......................................................................................................................................75DisableToken for SMS OTP request................................................................................................................. 76DisableToken for SMS OTP response.............................................................................................................. 76DisableToken for SMS OTP error codes...........................................................................................................77

Unlocking SMS OTP credentials.................................................................................................................................. 77Unlock an SMS OTP credential................................................................................................................................77

Unlock for SMS OTP request............................................................................................................................78Unlock for SMS OTP response......................................................................................................................... 78UnlockToken for SMS OTP error codes............................................................................................................79

Getting Token Information for SMS OTP credentials............................................................................................... 79Sample GetTokenInformation for SMS OTP request........................................................................................ 79Sample GetTokenInformation for SMS OTP response..................................................................................... 80GetTokenInformation for SMS OTP error codes............................................................................................... 81

Sending a temporary security code for SMS OTP...................................................................................................82SendTemporaryPassword for SMS OTP request..............................................................................................82SendTemporaryPassword for SMS OTP response........................................................................................... 83SendTemporaryPassword for SMS OTP error codes....................................................................................... 84

SMS message templates............................................................................................................................................... 84Default message types for the SMS message template.......................................................................................... 84Customized SMS OTP message request.................................................................................................................85

Register for SMS OTP.......................................................................................................................................85SendOTP for SMS OTP.................................................................................................................................... 85SendTemporaryPassword for SMS OTP........................................................................................................... 85

Voice OTP credential APIs................................................................................................................87Registering a Voice OTP credential............................................................................................................................. 87Using the Voice OTP credential................................................................................................................................... 87Voice OTP Credential APIs............................................................................................................................................88

Registering a Voice OTP credential......................................................................................................................... 88Register for Voice OTP request........................................................................................................................ 88Register for Voice OTP response......................................................................................................................90Register for Voice OTP error codes..................................................................................................................90

Activating a Voice OTP credential............................................................................................................................ 91ActivateToken for Voice OTP request............................................................................................................... 91

5


Sample ActivateToken for Voice OTP response............................................................................................... 92ActivateToken for Voice OTP error codes......................................................................................................... 92

SendOTP for Voice OTP.......................................................................................................................................... 93SendOTP for Voice OTP request...................................................................................................................... 93SendOTP for Voice OTP response................................................................................................................... 94SendOTP for Voice OTP error codes................................................................................................................94

Validate for Voice OTP..............................................................................................................................................95Validate for Voice OTP request......................................................................................................................... 95Validate for Voice OTP response...................................................................................................................... 96Validate for Voice OTP error codes...................................................................................................................97

Additional Voice OTP APIs............................................................................................................................................97DeactivateToken for Voice OTP................................................................................................................................98

DeactivateToken for Voice OTP request........................................................................................................... 98DeactivateToken for Voice OTP response.........................................................................................................99DeactivateToken for Voice OTP error codes.....................................................................................................99

EnableToken for Voice OTP..................................................................................................................................... 99EnableToken for Voice OTP request............................................................................................................... 100EnableToken for Voice OTP response............................................................................................................ 100EnableToken for Voice OTP error codes.........................................................................................................101

DisableToken for Voice OTP...................................................................................................................................101DisableToken for Voice OTP request.............................................................................................................. 102DisableToken for Voice OTP response........................................................................................................... 102DisableToken for Voice OTP error codes........................................................................................................103

Getting Token Information for Voice OTP credentials............................................................................................ 103GetTokenInformation for Voice OTP request...................................................................................................103GetTokenInformation for Voice OTP response................................................................................................104GetTokenInformation for Voice OTP error codes............................................................................................ 105

Sending a temporary security code for Voice OTP................................................................................................106SendTemporaryPassword for Voice OTP request...........................................................................................106SendTemporaryPassword for Voice OTP response........................................................................................ 107SendTemporaryPassword for Voice OTP error codes.................................................................................... 108

Unlocking Voice OTP credentials...............................................................................................................................108Unlock a Voice OTP credential...............................................................................................................................109

Unlock for Voice OTP request.........................................................................................................................109Sample Unlock for Voice OTP response.........................................................................................................109UnlockToken error codes................................................................................................................................. 110

Voice messaging.......................................................................................................................................................... 110Service-generated OTP credential APIs........................................................................................ 112

Registering a Service-generated OTP credential..................................................................................................... 112Using the Service-generated OTP credential............................................................................................................112

6


Service-generated OTP credential APIs.................................................................................................................... 113Registering a Service-generated OTP credential................................................................................................... 113

Sample Register for Service-generated OTP request.....................................................................................113Register for Service-generated OTP response............................................................................................... 114Register for Service-generated OTP error codes............................................................................................115

Activating a Service-generated OTP credential......................................................................................................115ActivateToken for Service-generated OTP request......................................................................................... 115ActivateToken for Service-generated OTP response...................................................................................... 116ActivateToken for Service-generated OTP error codes...................................................................................117

Sending a Service-generated OTP.........................................................................................................................117SendOTP for Service-generated OTP request................................................................................................117SendOTP for Service-generated OTP response.............................................................................................118SendOTP for Service-generated OTP error codes......................................................................................... 119

Validating a Service-generated OTP...................................................................................................................... 119Validate for Service-generated OTP request...................................................................................................119Validate for Service-generated OTP response................................................................................................120Validate for Service-generated OTP error codes............................................................................................ 121

Additional Service-generated OTP APIs....................................................................................................................122DeactivateToken for Service-generated OTP......................................................................................................... 122

DeactivateToken for Service-generated OTP request.....................................................................................122DeactivateToken for Service-generated OTP response.................................................................................. 123DeactivateToken for Service-generated OTP error codes...............................................................................124

EnableToken for Service-generated OTP............................................................................................................... 124EnableToken for Service-generated OTP request...........................................................................................124EnableToken for Service-generated OTP response........................................................................................125EnableToken for Service-generated OTP error codes.................................................................................... 126

DisableToken for Service-generated OTP.............................................................................................................. 126DisableToken for Service-generated OTP request..........................................................................................126DisableToken for Service-generated OTP response....................................................................................... 127DisableToken for Service-generated OTP error codes................................................................................... 128

Getting Token Information for Service-generated OTP credentials........................................................................128Getting Token Information for Service-generated OTP credentials........................................................................128

GetTokenInformation for Service-generated OTP request.............................................................................. 128GetTokenInformation for Service-generated OTP response........................................................................... 129GetTokenInformation for Service-generated OTP error codes........................................................................130

Out-of-band Authentication using Voice Calls and SMS............................................................. 131Out-of-band Authentication using Voice Calls and SMS......................................................................................... 131Example user scenarios.............................................................................................................................................. 131

Verifying transactions by entering a response into a phone.................................................................................. 131Verifying transactions by entering a security code into a website..........................................................................133

7


Voice call Out-of-band Authentication APIs..............................................................................................................133Submit a voice call to prompt response from user request................................................................................... 133

Sample SOAP XML request............................................................................................................................134Submit a voice call to prompt response from user response.................................................................................135

Sample Submit a voice call to prompt response from user SOAP XML response......................................... 135Submit a voice call to prompt response from user error codes............................................................................. 135Poll for voice call completion.................................................................................................................................. 136

Poll for voice call completion request..............................................................................................................136Poll for voice call completion response...........................................................................................................136Poll for voice call completion error codes....................................................................................................... 137

Submit and Poll for voice call error codes............................................................................................................. 137SMS out-of-band authentication APIs........................................................................................................................138

Deliver a security code by SMS or voice call........................................................................................................ 138Deliver a security code by SMS or voice call request.................................................................................... 138Deliver a security code by SMS or voice call response..................................................................................139Deliver a security code by SMS or voice call error codes.............................................................................. 140

Verify a security code............................................................................................................................................. 140Verify security code request............................................................................................................................ 140Verify security code response..........................................................................................................................141Verify security code error codes......................................................................................................................141

VIP Web Services error codes....................................................................................................... 143Error details.................................................................................................................................................................. 146

Malformed request error details..............................................................................................................................146Authorization Failed error details............................................................................................................................147

Best practices for high availability and optimal performance.................................................... 149SMS short codes and long codes in VIP...................................................................................... 150

Sending an SMS message.......................................................................................................................................... 150European character support for international phone numbers.............................................................................. 150

Copyright Statement........................................................................................................................ 152

8


Overview

This guide is designed for developers who integrate Symantec VIP credentials into their applications. VIP credentials area shared second factor in a two-factor authentication protocol. The interface between applications and VIP is a SOAPWeb Services interface. This guide focuses on the SOAP Web Services interface between VIP and your client application.

This guide assumes that you have a system in place for provisioning VIP credentials to end users. This guide alsoassumes that you understand SOAP, Web Services, and XML, and that you are developing an application that uses WebServices to interface with VIP.

• Getting started• VIP Service credential management APIs• About the SMS OTP credential APIs• About the Voice OTP credential APIs• About the Service-generated OTP credential APIs• About the Out-of-band Authentication APIs• VIP Web Services error codes• About best practices for high availability and optimal performance• Using short codes and long codes with VIP

9


Getting started

Refer to the following to get started with VIP Web Services:

• Supported environments• Obtaining your VIP certificate• Testing your secure connection to VIP web services• Using Java to test your configuration• Using .NET to test your configuration

Getting startedRefer to the following to get started with VIP Web Services:

• Supported environments• Obtaining your VIP certificate• Testing your secure connection to VIP web services• Using Java to test your configuration• Using .NET to test your configuration

Supported environmentsVIP Web Services supports the 1.1 and 1.2 SOAP protocols (Document Literal).

For Java environments:

• JDK 1.7. Download this JDK from http://www.oracle.com/technetwork/java/javase/overview/index.htm• Java Axis client libraries. To download these, go to: http://www.apache.org/dyn/closer.cgi/axis/axis/java/1.4/. Select a

package titled axis-src- to obtain all of the required files.

For .NET environments:

• .NET Framework run-time 2.0. To download the .NET Framework, go to: http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en

• .NET SDK 2.0. To download the .NET SDK, go to: http://www.microsoft.com/downloads/details.aspx?familyid=FE6F2099-B7B4-4F47-A244-C96D69C35DEC&displaylang=en

By default, VIP Web Services runs in a production environment. You can use the production environment for all of yourtesting by initially restricting your user groups to small pilot groups. Once testing is complete, open up the productionsystem to all of your users. However, if you require a test environment, contact your Symantec representative to obtainaccess to one.

Obtaining your VIP certificateYou need a certificate for client authentication to secure communications and identify yourself to the VIP Service. Incommunications with the VIP Service, the VIP certificate is used as a TLS/SSL client certificate. You can obtain a VIPcertificate from VIP Manager.

• Responsibility: Customer• Time to Completion: Varies

Complete the following steps to obtain a VIP certificate:

10

http://www.oracle.com/technetwork/java/javase/overview/index.htm

http://www.apache.org/dyn/closer.cgi/axis/axis/java/1.4/

http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en


http://www.microsoft.com/downloads/details.aspx?familyid=FE6F2099-B7B4-4F47-A244-C96D69C35DEC&displaylang=en



1. Sign in to VIP Manager (https://manager.vip.symantec.com). You need your credential.

2. From the dashboard, select Account in the navigation bar at the top of the page.

3. Select the Manage VIP Certificates link on the right side of the page.

4. Select Request a Certificate. Review the certificate instructions and select Continue.

5. Enter a name for your certificate that is easy to remember. Do not generate a CSR.

6. Select Submit Request.

Select the certificate format. For example, if your Validation & ID Protection uses:

• OpenSSL or PHP, and select PEM Format.• Java or .NET, and select PKCS#12.

7. Enter a password to protect access to this certificate. The password must be at least eight characters and include oneuppercase and one lowercase letter, plus one number.

Do not lose this password. You need it to install the certificate.

8. Click Download Certificate. You are prompted to save the file to your local system. You can return to this page at anytime to download this certificate again.

After you install your VIP certificate, you can test your configuration to verify that you can communicate with VIP.

See Testing your secure connection to VIP web services.

Testing your secure connection to VIP web servicesAfter you install your VIP certificate, the next step is to test your configuration to verify that you can use your VIPcertificate to communicate with VIP.

See Obtaining your VIP certificate.

The examples in this section make a getTokenInformation call to the Web Service. A getTokenInformation call retrievesbasic information about a particular credential. Substitute one of your credential IDs in the appropriate location in theexample appropriate for your configuration. Substitute one of your credential IDs in the appropriate location in the exampleappropriate for your configuration.

• Using Java to test your configuration• Using .NET to test your configuration

Using Java to test your configurationYou can write a client program for VIP using Axis in the Java environment. Note the following prerequisites:

• A pkcs#12 VIP certificate from VIP Manager.See Obtaining your VIP certificate

• JDK 1.7. Download this JDK from http://www.oracle.com/technetwork/java/javase/overview/index.htm• Java Axis client libraries. To download these, go to: http://www.apache.org/dyn/closer.cgi/axis/axis/java/1.4/. Select a

package titled axis-src- to obtain all of the required files.

Creating and running the sample Java test program

To create a sample test program, complete the following steps. The commands in these steps are for the Windowsplatform. The commands for other platforms should be similar.

1. Set the CLASSPATH library and AXIS library path.

For example, for this path (typically, this is the path where Axis is installed):

11

https://manager.vip.symantec.com

http://www.oracle.com/technetwork/java/javase/overview/index.htm

http://www.apache.org/dyn/closer.cgi/axis/axis/java/1.4/


SET AXIS=java\axis_1_4\lib

Set the following (the path may be different on your computer.):

SET CLASSPATH=.;%AXIS%\axis-ant.jar;%AXIS%\axis.jar;%AXIS%\commons-discovery-0.2.jar; %AXIS%\commons-logging-1.0.4.jar;%AXIS%\jaxrpc.jar;%AXIS%\log4j-1.2.8.jar;%AXIS%\saaj.jar; %AXIS%\wsdl4j-1.5.1.jar;%AXIS%\mailapi_1_3_1.jar;%AXIS%\activation.jar

2. Create java classes or proxies using wsdl2Java:

• Copy vip_auth.wsdl from vipuserservices root.• Create Java classes or proxies using wsdl2Java:

java org.apache.axis.wsdl.WSDL2Java vip_auth.wsdl

javac com\symantec\vip\schemas\_2006\_08\vipservice\*.java

jar cvf vipservice.jar com\symantec\vip\schemas\_2006\_08\vipservice\*.class

3. Create a Java source file.

• Place the certificate file in the same directory as your java source file.• Name the file Credential.java and enter the following code in that file:

public class Credential

{

VipSoapInterfaceService service;

VipSoapInterface port;

String m_url;

String version = "3.1";

String nonce = "abcd1234";// unique per transaction - maybe

use uuid

String authAccount = null;

String certFile = "vip.p12"; // replace with your cert

file

String password = "password"; // replace with the password

for the cert

public Credential(String url)

{

try{

service = new VipSoapInterfaceServiceLocator();

m_url = url;

System.setProperty("javax.net.ssl.keyStoreType", "pkcs12");

System.setProperty("javax.net.ssl.keyStore", certFile);

System.setProperty("javax.net.ssl.keyStorePassword",

password);

}

catch (Exception e)

{

System.out.println("Exception : " + e);

}

}

public String GetServerTime()

{

try{

port = service.getvipServiceAPI(new java.net.URL

(m_url+"/prov/soap"));

GetServerTimeType x = new GetServerTimeType(version,nonce);

12


GetServerTimeResponseType resp = port.getServerTime(x);

BigInteger reason = new

BigInteger(resp.getStatus().getReasonCode());

if (reason.intValue() != 0){

System.out.println("Message = " + resp.getStatus().

getStatusMessage());

System.out.println("Error Detail = " + resp.getStatus().

getErrorDetail());

return null;

}else{

return (resp.getTimestamp().getTime().toString());

}

}

catch (Exception e)

{

System.out.println("GetServerTime(), Exception : " + e);

return null;

}

}

public void getTokenInformation(String TokenId)

{

try{

port = service.getvipServiceAPI(new java.net.URL

(m_url+"/mgmt/soap"));

TokenIdType tokenIDType = new TokenIdType();

tokenIDType.set_value(TokenId);

// A reseller account can perform operations on behalf of

//the customer account specified in AuthorizerAccountId.

//For non-reseller accounts (the default case) specify

//AuthorizerAccountId as null.

getTokenInformationType x = new

getTokenInformationType(version,nonce,null,tokenIDType);

getTokenInformationResponseType resp = port.

getTokenInformation(x);

BigInteger reason = new BigInteger(resp.getStatus().

getReasonCode());

if (reason.intValue() != 0){

System.out.println("Message = " +

resp.getStatus().getStatusMessage());

System.out.println("Error Detail = " +

resp.getStatus().getErrorDetail());

}else{

System.out.println("Result = " +

resp.getStatus().getStatusMessage());

System.out.println("Token Id = " +

resp.getTokenInformation().getTokenId());

System.out.println("Token Kind = " +

resp.getTokenInformation().getTokenKind());

System.out.println("Adapter = " +

resp.getTokenInformation().getAdapter());

System.out.println("Token Status = " +

13


resp.getTokenInformation().getTokenStatus());

System.out.println("Expiration Date = " +

resp.getTokenInformation().getExpirationDate().getTime().

toString());

if(resp.getTokenInformation().getTempPassword

ExpirationDate()!= null)

System.out.println("Temp pwd expiration Date = " +

resp.getTokenInformation().getTempPassword

ExpirationDate().getTime().toString());

System.out.println("Owner = " +

resp.getTokenInformation().getOwner().toString());

System.out.println("Last update = " +

resp.getTokenInformation().getLastUpdate().getTime().

toString());

}

}

catch (Exception e)

{

System.out.println("getTokenInformation(), Exception : " + e);

}

}

public static void main(String[] args)

{

String url = "https://services-auth.vip.symantec.com";

String token_id = "VSMB95922596"; //replace with a valid

Token Id

Credential c = new Credential(url);

System.out.println("Server Time = " + c.getServerTime());

c.getTokenInformation(token_id);

}

}

4. Compile and build the test program:

SET CLASSPATH=%CLASSPATH%;vipservice.jar;signature.jar

javac Credential.java

5. Run the test program:

java Credential

Using .NET to test your configurationYou can write a client program for VIP using C+ in the .NET environment. Note the following prerequisites:

• A pkcs#12 VIP certificate from VIP Manager.See Obtaining your VIP certificate.

• .NET Framework run-time 2.0. To download the .NET Framework, go to: http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en

• .NET SDK 2.0. To download the .NET SDK, go to: http://www.microsoft.com/downloads/details.aspx?familyid=FE6F2099-B7B4-4F47-A244-C96D69C35DEC&displaylang=en

Creating and running the sample C+ test program

14






To create a sample test program, complete the following steps:1. Set the framework and SDK path. The path may be different on your computer.

set SDK=D:\Microsoft.NET\SDK\v2.0

set FRAMEWORK=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

2. Create the XML type mapping files from the WSDL/XSD schema. The WSDL/XSD schema is located on VIP Manager.

%SDK%\Bin\wsdl.exe vip_auth.wsdl vip_auth.xsd vip_common_auth.xsd

3. Create a C+ source file. Name the file Credential.cs and enter the following code in that file:using System;

using System.IO;

using System.Security.Cryptography.X509Certificates;

public class Credential

{

vipSoapInterfaceService v;

String m_url;

String version = "3.1";

String nonce = "abcd1234"; // unique per transaction - maybe

use uuid

String certFile = "vip.p12"; // replace with your cert file

String password = "password"; // replace with the password

for the cert

public Credential(String url)

{

v = new vipSoapInterfaceService();

//uncomment the following line for SOAP 1.1

v.SoapVersion = System.Web.Services.Protocols.SoapProtocol

Version.Soap12;

m_url = url;

// Apply the client certificate

this.applyCert();

}

private void applyCert()

{

FileStream fs = File.Open(certFile, FileMode.Open, FileAccess.Read);

byte[] buffer = new byte[fs.Length];

int count = fs.Read(buffer, 0, buffer.Length);

fs.Close();

X509Certificate2 cert = new X509Certificate2(buffer, password);

v.ClientCertificates.Add(cert);

}

public String GetServerTime()

{

v.Url = m_url + "/prov/soap";

GetServerTimeType t = new GetServerTimeType();

t.Version = version;

t.Id = nonce;

GetServerTimeResponseType r = v.GetServerTime(t);

15


if (r.Status.ReasonCode[0] != 0x00){

Console.WriteLine("Message = " + r.Status.StatusMessage);

return null;

}else{

return r.Timestamp.ToString();

}

}

public void getTokenInformation(String TokenId)

{

v.Url = m_url + "/mgmt/soap";

getTokenInformationType a = new getTokenInformationType();

a.Version = version;

a.Id = nonce;

TokenIdType b = new TokenIdType();

b.Value = TokenId;

a.TokenId = b;

getTokenInformationResponseType r = v.getTokenInformation(a);

Console.WriteLine(r);

if (r.Status.ReasonCode[0] != 0x00){

Console.WriteLine("Message = " + r.Status.StatusMessage);

}else{

Console.WriteLine("Adapter = " + r.TokenInformation.Adapter);

Console.WriteLine("TokenKind = " +

r.TokenInformation.TokenKind);

Console.WriteLine("TokenStatus = " +

r.TokenInformation.TokenStatus);

Console.WriteLine("Expiration Date = " +

r.TokenInformation.ExpirationDate.ToString());

Console.WriteLine("TempPassword Expiration Date = " +

r.TokenInformation.TempPasswordExpirationDate.ToString());

Console.WriteLine("Owner = " +

r.TokenInformation.Owner.ToString());

Console.WriteLine("LastUpdate = " +

r.TokenInformation.LastUpdate.ToString());

}

}

public static void Main()

{

String url = "https://services-auth.vip.symantec.com";

String token_id = "VSMB95922596"; //replace with a valid Token Id

Credential c = new Credential(url);

Console.WriteLine("Server Time = " + c.getServerTime());

c.getTokenInformation(token_id);

}

}

4. Compile and build the test program:

%FRAMEWORK%\csc.exe vipSoapInterfaceService.cs Credential.cs

5. Run the test program:

Credential.exe

16


VIP Service credential management APIs

Use the VIP Service credential management APIs for all the common administrative functions that are needed to managecredentials for your end users.

See Credential management API overview.

For a credential management API to work successfully, a credential must be in the correct state for that API.

See Credential states.

The VIP Service also includes APIs for specific credential types:

• About the SMS OTP credential APIs• About the Voice OTP credential APIs• About the Service-generated OTP credential APIs• About the Out-of-band Authentication APIs

Credential statesFor a credential management API to work successfully, a credential must be in the correct state for that API. A credentialcan be in one of the states shown in Credential states. Credential state changes illustrates how you can change credentialstates using the VIP credential management APIs.

In addition to these credential states, some credentials can expire. When a credential expires, they can no longer be usedfor authentication, and the only operations allowed on them are:

• Validate (temporary security code only)• GetTokenInformation• SetTemporaryPassword• SetTemporaryPwdExpiration• GetTemporaryPwdExpiration

See Credential management API overview.

Table 1: Credential states

Credential State Definition

New The credential has never been used in the account.Enabled The credential is in active use in the account and is available for validation.Disabled The credential is in active use in the account, but is currently unavailable for validation. This

state is set voluntarily by administrative procedure, for example, if the credential is lost.Locked The credential is in active use in the account, but is currently unavailable for validation. This

state is set automatically by the system based on account settings for validation.Inactive The credential was previously in active use in the account, but it is no longer available for

validation.

17


Credential management API overviewCredential management APIs lists each credential management API, and cross-references the topics that contains moreinformation and code samples.

NOTE

Many of the VIP Service API names contain the words “token” and “OTP.” A token is another word for acredential (a security application that is stored on a hardware security device, security card, mobile phone, orcomputer). A one-time password (OTP) is another word for a security code (a unique code that a credentialgenerates to protect an end user’s identity).

18


For a credential management API to work successfully, a credential must be in the correct state for that API.


Table 2: Credential management APIs

API Name Description See

ActivateToken Activates a new credential. Activating credentialsDeactivateToken Changes the credential’s state to inactive. Deactivating credentialsValidate Authenticates a security code from credentials. ValidateValidateMultiple Authenticates a security code when a user has more than one

credential.Validating multiple credentials

ValidateCR Validates challenge/response. Validating challenge/response(CR) requests

Synchronize If a user does not authenticate with their credential for anextended time, the HOTP event-based credential becomes out ofsynchronization. The Synchronize API adjusts the Web Servicesclock (or counter) so that an Enabled credential’s security code isrestored to a valid range.Note that clicking the credential button too many times causesHOTP event-based credential to be out of synchronization.

Synchronizing credentials

UnlockToken Unlocks a credential if it has become locked. Unlocking credentialsDisableToken Disables a credential. Disabling credentialsEnableToken Enables a credential that you have disabled. If you disable

a credential, the user cannot use the credential until anadministrator sets it back to the Enabled state.

Enabling credentials

SetTemporaryPassword Sets a temporary security code for an Enabled or Disabledcredential.

Setting a temporary securitycode

GenerateTemporaryPasswordGenerates a temporary security code for an Enabled or Disabledcredential.

Generating a temporary securitycode

SetTemporaryPwdExpirationSets the expiration time and date for a credential’s temporarysecurity code.

Setting a temporary securitycode

GetTemporaryPwdExpirationRetrieves the expiration time and date for a credential’s temporarysecurity code.

Getting temporary security codeexpiration dates

CheckOTP Validates the security codes for locked credentials. Checking security codes onlocked credentials

getTokenInformation Gets information about a specific credential. Getting information about acredential

Activating and deactivating credentialsCredentials require activation after registration with the VIP Service. They can be deactivated if they will no longer beused.

• Activating credentials• Deactivating credentials

NOTE

All XML requests should be v2.0, as detailed in the API descriptions.

19


Activating credentialsUse the ActivateToken API to activate new or inactive credentials (see Credential state changes). If the activation issuccessful, the credential is Enabled and ready for use.

• Activation request• Activation response• ActivateToken error codes

Activation requestActivateToken input fields provides details about the activation input fields. Send the request to:

https://services-auth.vip.symantec.com/mgmt/soap

Table 3: ActivateToken input fields

Input Field Required? Type Purpose

TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.

OTP1 N String One-time passwords (OTPs) are security codes generatedusing the credential. Optionally, send either none, one,or two consecutive security codes. The VIP Service WebServices check any security codes against the credential IDto verify the validity of the credential.

OTP2 N String One-time passwords (OTPs) are security codes generatedusing the credential. Optionally, send either none, one,or two consecutive security codes. The VIP Service WebServices check any security codes against the credential IDto verify the validity of the credential.

See Sample ActivateToken SOAP XML request.

Sample ActivateToken SOAP XML request

<?xml version="1.0" encoding="UTF-8" ?>

<SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:ns3="http://www.w3.org/2000/09/xmldsig#"

xmlns:ns1="https://schemas.vip.symantec.com/2006/08/vipservice">

<SOAP-ENV:Body>

<ns1:ActivateToken Version="3.1" Id="EHCF6443">

<ns1:TokenId>VSMB57361338</ns1:TokenId>

<ns1:OTP1>306491</ns1:OTP1>

<ns1:OTP2>408054</ns1:OTP2>

</ns1:ActivateToken>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

20



Activation responseActivateToken output fields provides details about the ActivateToken output fields.

Table 4: ActivateToken output fields

Output Field Required? Type Purpose

ReasonCode Y hexBinary If an activation request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully activated.SameInitialState N boolean States whether the credential changed states.


See Sample ActivateToken SOAP XML response.

Sample ActivateToken SOAP XML response


<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<Body>

<ActivateTokenResponse RequestId="EHCF6443" Version="3.1"

xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">

<Status>

<ReasonCode>0000

<StatusMessage>Success

</Status>

<SameInitialState>false

</ActivateTokenResponse>

</Body>

</Envelope>

ActivateToken error codes

This section lists the error codes you may encounter using the ActivateToken API.

See VIP Web Services error codes.

4845: The request parameters you supplied contain an unexpected value

or format.

4923: The OTP you provided is within the Sync window, but outside the

Look Ahead Window. This operation requires a second consecutive OTP

4990: Bad Token State

4993: Operation not allowed on a disabled token

4994: Operation not allowed on a locked token

49b5: Failed with an invalid security code

49f2: Token ID not found

4e00: Malformed request

4e01: Service Internal Error

4e02: Authentication failed

4e03: Authorization failed

4e04: Unsupported service protocol version

4e0b: VIP certificate revoked

21


4e10: This URL does not support this operation

4e11: Token ID has been revoked

4f05: This VIP credential or VIP credential type is not supported for

this account

Deactivating credentialsUse the DeactivateToken API to deactivate credentials.

• Deactivation request• Deactivation response• DeactivateToken error codes

If you no longer want to allow a credential to be used on your website, deactivate it by setting it to the Inactive state.


When you deactivate a token, you can also specify the reason you deactivated it. This information is used in part toprovide network-wide intelligence information for the token.

• DisableToken input fields• Using Network Intelligence

Deactivation requestDeactivateToken input fields provides details about the DeactivateToken input fields. Send the request to:


Table 5: DeactivateToken input fields



Reason N String To specify the reason for deactivating the token.This field is optional and applies only to VIP NetworkEnabled (non-sharing) credentials.

See Sample DeactivateToken SOAP XML request.

Sample DeactivateToken SOAP XML request


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/

envelope/"






<SOAP-ENV:Body>

<ns1:DeactivateToken Version="3.1" Id="JFGJ7808">


<ns1:Reason>Lost</ns1:Reason>

22



</ns1:DeactivateToken>

</SOAP-ENV:Body>


Deactivation responseDeactivateToken output fields provides details about the DeactivateToken output fields.

Table 6: DeactivateToken output fields


ReasonCode Y hexBinary If a deactivation request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully deactivated.SameInitialState N boolean States whether the credential changed states.

Credential states

See Sample DeactivateToken SOAP XML response.

Sample DeactivateToken SOAP XML response



<Body>

<DeactivateTokenResponse RequestId="JFGJ7808" Version="3.1"


<Status>

<ReasonCode>0000</ReasonCode>

<StatusMessage>Success</StatusMessage>

</Status>

<SameInitialState>false</SameInitialState>

</DeactivateTokenResponse>

</Body>

</Envelope>

DeactivateToken error codesThis section lists the error codes you may encounter using the DeactivateToken API. For additional information,



4995: Operation not allowed on a new token










23


Validating credentialsUse the Validate Credential APIs to authenticate credentials:

• Validate• Validating multiple credentials• Validating challenge/response (CR) requests

ValidateUse the Validate API to authenticate credentials. To authenticate an Enabled credential, send a Validate call including thecredential ID and a security code. Credentials are validated according to the security profile for that credential type. TheValidate API can also be used to validate temporary security codes.

See Validate input fields.

When you send a Validate call, the VIP Service Web Services check the validity of the security code and return aresponse.

• Validation request• Validation response• Validation error codes

Validation requestValidate input fields provides details about the Validate input fields. Send the request to:

https://services-auth.vip.symantec.com/val/soap

Table 7: Validate input fields


TokenIds Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.

OTP N String A one-time password (OTP) is a security code generatedusing the credential. The VIP Service Web Services checkthe security code against the credential ID to verify thevalidity of the credential. An OTP can also be a temporarysecurity code.

Note: For disabled or expired credentials, you must send atemporary security code instead of an OTP.

See Setting and managing temporary security codes.

See Sample Validate SOAP XML request.

Sample Validate SOAP XML request



envelope/"





24




<SOAP-ENV:Body>

<ns1:Validate Version="3.1" Id="CDCE1500">


<ns1:OTP>893818</ns1:OTP>

</ns1:Validate>

</SOAP-ENV:Body>


Validation responseValidate output fields lists the Validate output fields.

Table 8: Validate output fields


ReasonCode Y hexBinary If a validation request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully validated.TokenCategoryDetails Y Array Shows detailed information about the credential:

• CategoryId identifies the credential category.• FormFactor further identifies the credential type. Each

credential is one of the following:– CONNECTED– DESKTOP– DISPLAYCARD– KEYFOB– MOBILE– SERVICE– SMS– TMPPWD– VOICE

• MovingFactor identifies the security code generationmethod. Each credential generates security codes byone of the following methods:– TIME– EVENT– NONE (returned for temporary security codes only)

• OtpGeneratedBy identifies whether the security code isgenerated in hardware or software.

See Sample Validate SOAP XML response.

Sample Validate SOAP XML response



<Body>

<ValidateResponse RequestId="CDCE1500" Version="3.1"


<Status>

25




</Status>

<TokenCategoryDetails>

<CategoryId>69</CategoryId>

<FormFactor>MOBILE</FormFactor>

<MovingFactor>EVENT</MovingFactor>

<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>

</TokenCategoryDetails>

</ValidateResponse>

</Body>

</Envelope>

Validation error codesThis section lists the error codes you may encounter using the Validate API.


4879: The service is temporarily unavailable





4996: Operation not allowed on an inactive token

4997: Validation failed











4bf1: This credential type does not support this operation

Validating multiple credentialsUse the ValidateMultiple API to validate one of several credentials. To authenticate a user with multiple credentials, send aValidateMultiple API call to check all of the user’s credentials against a single security code.

• Validation request for multiple credentials• Validation response for multiple credentials• ValidateMultiple error codes

Validation request for multiple credentialsValidateMultiple input fields provides details about the ValidateMultiple input fields. Send the request to:


26



Table 9: ValidateMultiple input fields


An array of TokenIds Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.

OTP N String A one-time password (OTP) is a security code generatedusing the credential. The VIP Web Services check thesecurity code against all of the credential IDs to verify thevalidity of the credential.

SendSuccessfulTokenId N Boolean If this field is set to true, the response contains the token ID(credential ID) for any successfully validated credential.

See Sample ValidateMultiple SOAP XML request.

Sample ValidateMultiple SOAP XML request

<?xml version="1.0" encoding="UTF-8"?>

<ValidateMultiple xmlns="https://schemas.vip.symantec.com/2006/08/

vipservice" xmlns:ds="http://www.w3.org/2000/09/xmldsig<"


xsi:schemaLocation="https://schemas.vip.symantec.com/

2006/08/vipservice" Version="3.1" Id="1234abcd">

<TokenIds>VSMB45948855</TokenIds>



<OTP>046226</OTP>

<SendSuccessfulTokenId>true</SendSuccessfulTokenId>

</ValidateMultiple>

Validation response for multiple credentialsValidateMultiple output fields lists the ValidateMultiple output fields.

Table 10: ValidateMultiple output fields


ReasonCode Y hexBinary If a validation attempt is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully validated.SuccessfulTokenId N String Identifies the token ID (credential ID) for the credential that

was successfully validated.

27



TokenCategoryDetails Y Array Shows detailed information about the credential:• CategoryId identifies the credential category.• FormFactor further identifies the credential type. Each



• OtpGeneratedBy identifies whether the security codeis generated in hardware or software.

See Sample ValidateMultiple SOAP XML response.

Sample ValidateMultiple SOAP XML response


<ValidateMultipleResponse RequestId="1234abcd" Version="3.1" xmlns=

"https://schemas.vip.symantec.com/2006/08/vipservice">

<Status>



</Status>

<SuccessfulTokenId>VSMB45948855</SuccessfulTokenId>







</ValidateMultipleResponse>

ValidateMultiple error codesThis section lists the error codes you may encounter using the ValidateMultiple API.






28



4996: Operation not allowed on a inactive token

4997: Validation failed.











Validating challenge/response (CR) requestsUse the ValidateCR API to validate challenge/response requests. The primary use case for challenge/response-basedauthentication is financial transaction signing. When a transaction needs to be signed, the user receives a challenge. Thischallenge is typically a request for one or more of the following:

• A transaction ID• The last four digits from the user’s account• The amount being transferred

The user enters the challenge in a handheld device. The device generates a response which is then validated using theValidateCR API.

• ValidateCR request• ValidateCR response• ValidationCR error codes

ValidateCR requestValidateCR input fields provides details about the ValidateCR input fields. Send the request to:


Table 11: ValidateCR input fields


TokenIds Y String The given Challenge/Response is validated against one ormore token IDs provided in this array.

NumericChallenge N Number The challenge, represented as a decimal number (8 to64 digits). If NumericChallenge is sent, do not sendHexChallenge.

HexChallenge N Hex String The challenge, represented as a hex string (always 40hex digits in length). If HexChallenge is sent, do not sendNumericChallenge.

Response Y Number The numeric response (typically 6 digits) to theNumericChallenge, and which is generated by the user'scredential.

29




CheckOnly Y Boolean Specifies if an invalid response should count as a failedattempt. If this field is set to false (the default value), afailure increases the number of bad attempts. If this field isset to true, a failure does not cause any side effects.

Usage N String Usage is identified as either SIGNING orAUTHENTICATION. Currently, SIGNING is the only usagesupported.

See Sample ValidateCR request.

Sample ValidateCR request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/

envelope/" xmlns:vip="https://schemas.vip.symantec.com/2006/08/

vipservice"

xmlns:xd="http://www.w3.org/2000/09/xmldsig#">

<soapenv:Header/>

<soapenv:Body>

<vip:ValidateCR Version = "3.1" Id="abcd123">

<vip:TokenIds>VSOC99000019</vip:TokenIds>

<vip:NumericChallenge>123456</vip:NumericChallenge>

<vip:Response>675792</vip:Response>

<vip:CheckOnly>false</vip:CheckOnly>

<vip:Usage>SIGNING</vip:Usage>

</vip:ValidateCR>

</soapenv:Body>

</soapenv:Envelope>

ValidateCR responseValidateCR output fields lists the ValidateCR output fields.

Table 12: ValidateCR output fields


ReasonCode Y Hex string Specifies the result of the operation. 0000 means success.StatusMessage Y String A status message corresponding to the ReasonCode.SuccessfulTokenId N String Only in case of success, this field contains the successful

token ID.

30







See Sample ValidateCR SOAP XML response.

Sample ValidateCR SOAP XML response


<Body>

<ValidateCRResponse RequestId="abcd123" Version="3.1" xmlns=


<Status>



</Status>

<SuccessfulTokenId>VSOC99000019</SuccessfulTokenId>







</ValidateCRResponse>

</Body>

</Envelope>

ValidationCR error codesThis section lists the error codes you may encounter using the ValidateCR API.



31







4997: Validation failed










4f05: The policy for this account does not support this VIP credential

or VIP credential type

4bf1: This credential type does not support this operation.

Synchronizing credentialsWhen a user does not use their credential for an extended period of time, it gets out of synchronization. Synchronizationwith VIP Service corrects the credential.

The Synchronize API restores a credential to synchronization. To synchronize a credential that is out of synchronization,send a synchronize call and include the credential ID and two consecutive security codes. When you send a synchronizecall, the VIP Service Web Services check the validity of the security codes, and return a response.

NOTE

SMS credentials do not need to be synchronized.

• Synchronization request• Synchronization response• Synchronize error codes

Synchronization requestSynchronize input fields provides details about the Synchronize input fields. Send the request to:


Table 13: Synchronize input fields



OTP1 Y String One-time passwords (OTPs) are security codes generatedusing the credential. If you send two consecutive securitycodes, the VIP Service checks the security codes againstthe credential ID to verify the credentials’ validity.

32




OTP2 Y String One-time passwords (OTPs) are security codes generatedusing the credential. If you send two consecutive securitycodes, the VIP Service checks the security codes againstthe credential ID to verify the credentials’ validity.

See Sample Synchronize SOAP XML request.

Sample Synchronize SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>


envelope/"






<SOAP-ENV:Body>

<ns1:Synchronize Version="3.1" Id="GJBC8741">


<ns1:OTP1>061792</ns1:OTP1>

<ns1:OTP2>165689</ns1:OTP2>

</ns1:Synchronize>

</SOAP-ENV:Body>


Synchronization responseSynchronization output fields lists the Synchronize output fields.

Table 14: Synchronization output fields


ReasonCode Y hexBinary If a synchronization request is unsuccessful, theReasonCode provides the reason.

StatusMessage Y String States whether the credential was successfullysynchronized.

See Sample Synchronize SOAP XML response.

Sample Synchronize SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>


<Body>

<SynchronizeResponse RequestId="GJBC8741" Version="3.1"


<Status>



33


</Status>

</SynchronizeResponse>

</Body>

</Envelope>

Synchronize error codesThis section lists the error codes you may encounter using the Synchronize API.


4845: The request parameters you supplied contain an unexpected value or

format.






49f2: Token ID not found.










Unlocking credentialsCredentials become locked when they exceed the configured number of allowed continuous validation failures.

Use the UnlockToken API to unlock those credentials that have become locked. Unlocking a credential changes the stateof the credential from Locked to Enabled and makes it ready for use (see Credential state changes).

• Unlock request• Unlock response• UnlockToken error codes

NOTE

Verify that a user is in possession of their credential before you unlock it. First, verify the user’s identity throughsome other means, and then request a security code from the user. To check the security code, use theCheckOTP API. If the CheckOTP call succeeds, then make an UnlockToken call.

Unlock requestUnlockToken input fields provides details about the UnlockToken input field. Send the request to:


34



Table 15: UnlockToken input fields



See Sample UnlockToken SOAP XML request.

Sample UnlockToken SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>


envelope/"






<SOAP-ENV:Body>

<ns1:UnlockToken Version="3.1" Id="BGFA5527">


</ns1:UnlockToken>

</SOAP-ENV:Body>


Unlock responseUnlockToken output fields provides details about the UnlockToken output fields.

Table 16: UnlockToken output fields


ReasonCode Y hexBinary If an unlock request is unsuccessful, theReasonCode provides the reason.

StatusMessage Y String States whether the credential wassuccessfully unlocked.

SameInitialState N boolean States whether the credential changedstates.See Credential states.

See Sample UnlockToken SOAP XML response.

Sample UnlockToken SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>


<Body>

<UnlockTokenResponse RequestId="BGFA5527" Version="3.1"


<Status>

35




</Status>


</UnlockTokenResponse>

</Body>

</Envelope>

UnlockToken error codesThis section lists the error codes you may encounter using the UnlockToken API.















Disabling credentialsDisable credentials when they are reported lost, stolen, or returned for a refund. Disabling a credential changes its statefrom Enabled or Locked to Disabled, and makes it unavailable for use (see Credential state changes). For example, anissuer should disable a credential if an end-user reports that the credential has been forgotten, lost, or stolen.

Use the DisableToken API to disable a credential.

• Disable request• Disable response• DisableToken error codes

When you disable a token, you can also specify the reason you disabled it. This information is used in part to providenetwork-wide intelligence information for the token.

• Using Network Intelligence• Reason codes for a disabled and deactivated credential

Disabling credentialsDisable credentials when they are reported lost, stolen, or returned for a refund. Disabling a credential changes its statefrom Enabled or Locked to Disabled, and makes it unavailable for use (see Credential state changes). For example, anissuer should disable a credential if an end-user reports that the credential has been forgotten, lost, or stolen.

Use the DisableToken API to disable a credential.

36


• Disable request• Disable response• DisableToken error codes

When you disable a token, you can also specify the reason you disabled it. This information is used in part to providenetwork-wide intelligence information for the token.

• Using Network Intelligence• Reason codes for a disabled and deactivated credential

Disable requestDisableToken input fields provides details about the DisableToken input fields. Send the request to:


Table 17: DisableToken input fields



Reason N String To specify the reason for disabling the token.This field is optional and applies only to VIP NetworkEnabled versions.

See Sample DisableToken SOAP XML request.

Sample DisableToken SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:DisableToken Version="3.1" Id="JEJI2285">



</ns1:DisableToken>

</SOAP-ENV:Body>


Disable responseDisable output fields provides details about the DisableToken output fields.

37



Table 18: Disable output fields


ReasonCode Y hexBinary If a disable request is unsuccessful, theReasonCode provides the reason.

StatusMessage Y String States whether the credential wassuccessfully disabled.

SameInitialState N boolean States whether the credential changedstates.See Credential states.

See Sample DisableToken SOAP XML response.

Sample DisableToken SOAP XML response



<Body>

<DisableTokenResponse RequestId="JEJI2285" Version="3.1" xmlns=


<Status>



</Status>


</DisableTokenResponse>

</Body>

</Envelope>

DisableToken error codesThis section lists the error codes you may encounter using the DisableToken API.














Enabling credentialsCredentials cannot be used, tested, or synchronized unless they are Enabled. Use the EnableToken API to enablecredentials that an issuer has disabled.

38


See Disabling credentials.

Use this operation to change the state of a disabled credential to Enabled (see Credential state changes). When youEnable a credential, VIP Service Web Services check the validity of the credential ID and return a response. If the enableoperation is successful, the credential changes from Disabled to Enabled and is ready for use.

• Enable request• Enable response• EnableToken error codes

Enable requestEnable input fields provides details about the EnableToken input field. Send the request to:


Table 19: Enable input fields


TokenId Y String The token ID (credential ID) identifies the credential to the VIPService Web Services.

See Sample EnableToken SOAP XML request.

Sample EnableToken SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>


envelope/"






<SOAP-ENV:Body>

<ns1:EnableToken Version="3.1" Id="IAHD7313">


</ns1:EnableToken>

</SOAP-ENV:Body>


Enable requestEnable input fields provides details about the EnableToken input field. Send the request to:


Table 20: Enable input fields


TokenId Y String The token ID (credential ID) identifies the credential to the VIPService Web Services.

39




See Sample EnableToken SOAP XML request.

Sample EnableToken SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>


envelope/"






<SOAP-ENV:Body>

<ns1:EnableToken Version="3.1" Id="IAHD7313">


</ns1:EnableToken>

</SOAP-ENV:Body>


EnableToken error codesThis section lists the error codes you may encounter using the EnableToken API.















Setting and managing temporary security codesIf a user temporarily does not have access to the credential (for example, left it at home), you can provide the user with atemporary security code.

This section applies to physical credentials only. Additional APIs expressly for setting and managing temporary securitycodes with other credential types are described in the following topics:

• About the SMS OTP credential APIs• About the Voice OTP credential APIs• About the Service-generated OTP credential APIs

Temporary security codes are six numeric characters, and are valid for a fixed period of time. They expire on the date youset when you create the temporary security code or the date you specify in a SetTemporaryPwdExpiration API call. Whena user enters a temporary security code for authentication, the validation succeedS as long as:

40


• The temporary security code is set using the SetTemporaryPassword API.• The temporary security code is not expired.• The user enters the temporary security code correctly.

You can set the temporary security code expiration date and time, based on the circumstances for that particular user. Youcan also check the expiration date and time for a user. See the following sections for information on setting and managingtemporary security codes:

• Setting temporary security codes.See Setting a temporary security code.

• Generating temporary security codes.See Generating a temporary security code.

• Setting temporary security code expiration dates.See Setting temporary security code expiration dates .

• Getting temporary security code expiration dates and times.See Getting temporary security code expiration dates.

• Sending temporary security codes to mobile devices through SMS. VIP Service can generate and send temporarysecurity codes to a mobile device through the SMS Gateway.See Sending a temporary security code.

The APIs for setting temporary security code expiration dates accept input with millisecond granularity. However, the VIPService Web Services ignore the millisecond component of the expiration date.

Setting a temporary security codeUse the SetTemporaryPassword API to set a temporary security code for a credential. You can optionally set an expirationdate for the security code, or set it for one-time use only. The request requires the credential ID and the temporarysecurity code string.

You can also use the SetTemporaryPassword API to clear a temporary security code. To clear the temporary securitycode, send the SetTemporaryPassword API and leave the TemporaryPassword request parameter empty.

NOTE

The SetTemporaryPassword API works on both Disabled and Enabled credentials. Check the credentialstate before issuing a temporary security code. Checking the credential state prevents users from trying toauthenticate using disabled credentials.

See Getting information about a credential.

• SetTemporaryPassword request.• SetTemporaryPassword response.• etTemporaryPassword error codes.

SetTemporaryPassword requestSetTemporaryPassword input fields provides details about the SetTemporaryPassword input fields. Send the request to:


41



Table 21: SetTemporaryPassword input fields



TemporaryPassword Y String The temporary security code is either empty or six numericcharacters.

ExpirationDate N dateTime The temporary security code expiration date (maximumof 30 days). If no date is provided, the default expirationperiod set for your account in VIP Manager is used tocalculate the security code expiration.

OneTimeUseOnly N Boolean If this field is set to “true,” the temporary security codeexpires after one use, or at the expiration date. The defaultvalue is “false.”

See Sample SetTemporaryPassword SOAP XML request.

Sample SetTemporaryPassword SOAP XML request



envelope/";

xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/";

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";

xmlns:xsd="http://www.w3.org/2001/XMLSchema";

xmlns:ns3="http://www.w3.org/2000/09/xmldsig#";

xmlns:ns1="https://schemas.vip.symantec.com/2006/08/vipservice">;

<SOAP-ENV:Body>

<ns1:SetTemporaryPassword Version="3.1" Id="GJGB2050">


<ns1:TemporaryPassword>abc123</ns1:TemporaryPassword>

<ns1:ExpirationDate>2008-08-06T10:33:49-08:00</ns1:ExpirationDate>

<ns1:OneTimeUseOnly>false</ns1:OneTimeUseOnly>

</ns1:SetTemporaryPassword>

</SOAP-ENV:Body>


SetTemporaryPassword responseSetTemporaryPassword output fields provides details about the SetTemporaryPassword output fields.

Table 22: SetTemporaryPassword output fields


ReasonCode Y hexBinary If the request to set a temporary security code isunsuccessful, the ReasonCode provides the reason.

StatusMessage Y String States whether the temporary security code wassuccessfully set.

See Sample SetTemporaryPassword SOAP XML response.

42


Sample SetTemporaryPassword SOAP XML response



<Body>

<SetTemporaryPasswordResponse RequestId="IGEH4431" Version="3.1"


<Status>



</Status>

</SetTemporaryPasswordResponse>

</Body>

</Envelope>

SetTemporaryPassword error codesThis section lists error codes you may encounter using the SetTemporaryPassword API.


4952: The temporary password does not contain the correct number of

numeric characters

4953: Expiration date must be later than the current time, and no more

than 7 days from now














Generating a temporary security codeUse the GenerateTemporaryPassword API to generate a temporary security code for a credential. You can optionally setan expiration date for the security code, or set it for one-time use only. The request requires the credential ID.

NOTE

The GenerateTemporaryPassword API works on both Disabled and Enabled credentials. Check the credentialstate before issuing a temporary security code. Checking the credential state prevents users from trying toauthenticate using disabled credentials.

See Getting information about a credential.

43


• GenerateTemporaryPassword request• GenerateTemporaryPassword response• GenerateTemporaryPassword error codes

GenerateTemporaryPassword requestGenerateTemporaryPassword input fields provides details about the GenerateTemporaryPassword input fields. Send therequest to:


Table 23: GenerateTemporaryPassword input fields



ExpirationDate N dateTime The temporary security code expiration date (maximum ofseven days). If no date is provided, the default expirationperiod is used to calculate the security code expiration.

OneTimeUseOnly N Boolean If this field is set to “true,” the temporary security codeexpires after one use, or at the expiration date. The defaultvalue is “false.”

See Sample GenerateTemporaryPassword SOAP XML request.

Sample GenerateTemporaryPassword SOAP XML request

<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"


xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<GenerateTemporaryPassword xmlns="https://schemas.vip.symantec.com/

2006/08/vipservice"

Version="3.1" Id="1234abcd">

<TokenId type="Voice">16504265083</TokenId>

<ExpirationDate>2008-08-06T10:33:49-08:00</ExpirationDate>

<OneTimeUseOnly>true</OneTimeUseOnly>

</GenerateTemporaryPassword>

</soapenv:Body>

</soapenv:Envelope>

GenerateTemporaryPassword responseGenerateTemporaryPassword output fields provides details about the GenerateTemporaryPassword output fields.

44



Table 24: GenerateTemporaryPassword output fields


ReasonCode Y hexBinary If the request to generate a temporary security code isunsuccessful, the ReasonCode provides the reason.

StatusMessage Y String States whether the temporary security code wassuccessfully generated.

TemporaryPassword Y String The temporary security code is six numeric characters.

See Sample GenerateTemporaryPassword SOAP XML response.

Sample GenerateTemporaryPassword SOAP XML response



<Body>

<GenerateTemporaryPasswordResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>

<TemporaryPassword>972947</TemporaryPassword>

</GenerateTemporaryPasswordResponse>

</Body>

</Envelope>

GenerateTemporaryPassword error codesThis section lists error codes you may encounter using the GenerateTemporaryPassword API.


4953: Expiration date must be later than the current time, and no

more than 7 days from now














45


Setting temporary security code expiration datesUse the SetTemporaryPwdExpiration API to change the expiration date for a temporary security code you previously setusing the SetTemporaryPwdExpiration API.

• SetTemporaryPwdExpiration request• SetTemporaryPwdExpiration response• SetTemporaryPwdExpiration error codes

SetTemporaryPwdExpiration requestSetTemporaryPwdExpiration input fields provides details about the SetTemporaryPwdExpiration input fields. Send therequest to:


Table 25: SetTemporaryPwdExpiration input fields



ExpirationDate N dateTime The date that you want the temporary security code toexpire (maximum 30 days). If you do not set an expirationdate, the VIP Service Web Services defaults to the numberof days from the date you make the API call that is set foryour account in VIP Manager.

See Sample SetTemporaryPwdExpiration SOAP XML request.

Sample SetTemporaryPwdExpiration SOAP XML request



envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"





<SOAP-ENV:Body>

<ns1:SetTemporaryPwdExpiration Version="3.1" Id="CCJH0357">



</ns1:SetTemporaryPwdExpiration>

</SOAP-ENV:Body>


SetTemporaryPwdExpiration responseSetTemporaryPwdExpiration output fields provides details about the SetTemporaryPwdExpiration output fields.

46



Table 26: SetTemporaryPwdExpiration output fields


ReasonCode Y hexBinary If the request to set the temporary security code expirationdate is unsuccessful, the ReasonCode provides thereason.

StatusMessage Y String States whether the temporary security code expiration datewas successfully set.

See Sample SetTemporaryPwdExpiration SOAP XML response.

Sample SetTemporaryPwdExpiration SOAP XML response



<Body>

<SetTemporaryPwdExpirationResponse RequestId="CCJH0357" Version="3.1"


<Status>



</Status>

</SetTemporaryPwdExpirationResponse>

</Body>

</Envelope>

SetTemporaryPwdExpiration error codesThis section lists the error codes you may encounter using the SetTemporaryPwdExpiration API.


4951: Invalid Request. You must set a temporary password for this

token before you can change the temporary password expiration date

4953: Expiration date must be later than the current time and no more

than 7 days from now















47


Getting temporary security code expiration datesUse the GetTemporaryPwdExpiration API to find out the expiration date for a credential for which a temporary securitycode is already set.

• GetTemporaryPwdExpiration request• GetTemporaryPwdExpiration response• GetTemporaryPwdExpiration error codes

GetTemporaryPwdExpiration requestSetTemporaryPwdExpiration input fields provides details about the GetTemporaryPwdExpiration input field. Send therequest to:


Table 27: SetTemporaryPwdExpiration input fields



See Sample GetTemporaryPwdExpiration SOAP XML request.

Sample GetTemporaryPwdExpiration SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:GetTemporaryPwdExpiration Version="3.1" Id="IGIC1317">


</ns1:GetTemporaryPwdExpiration>

</SOAP-ENV:Body>


GetTemporaryPwdExpiration responseGetTemporaryPwdExpiration output fields provides details about the GetTemporaryPwdExpiration output fields.

48



Table 28: GetTemporaryPwdExpiration output fields


ReasonCode Y hexBinary If a request to retrieve a security code expiration isunsuccessful, the ReasonCode provides the reason.

StatusMessage Y String States whether the temporary security code expiration wassuccessfully retrieved.

ExpirationDate Y dateTime The date that the temporary security code is set to expire.

See Sample GetTemporaryPwdExpiration SOAP XML response.

Sample GetTemporaryPwdExpiration SOAP XML response



<Body>

<GetTemporaryPwdExpirationResponse RequestId="IGIC1317" Version="3.1"


<Status>



</Status>

<ExpirationDate>2007-01-27T16:33:40.000-08:00</ExpirationDate>

</GetTemporaryPwdExpirationResponse>

</Body>

</Envelope>

GetTemporaryPwdExpiration error codesThis section lists the error codes you may encounter using the GetTemporaryPwdExpiration API.















4e12: Invalid Request. There is no temporary password associated with

this token


49


Sending a temporary security code for SMS OTPIf a user’s credential is lost or stolen, use the SendTemporaryPassword for SMS API to generate and send a temporarysecurity code to the user’s phone number. The system-generated, temporary security code is sent using SMS, and is validfor one use only. The temporary security code must be used before the specified expiration time (up to seven days).

To complete this operation, you must provide the user name and password for your account on the SMS Gateway.

• SendTemporaryPassword for SMS OTP request• SendTemporaryPassword for SMS OTP response• SendTemporaryPassword for SMS OTP error codes

Checking security codes on locked credentialsCredentials can be synchronized or validated when locked.

The CheckOTP API described in this section does not apply to SMS OTP, Voice OTP, or Service-generated OTPcredentials.

Use the CheckOTP API to validate or synchronize a credential even if the credential is locked.

• Validate• Synchronizing credentials• Validating multiple credentials

The CheckOTP API validates or synchronizes a credential based on the number of security codes you provide. If youprovide one security code, CheckOTP validates the credential. If you provide two security codes, CheckOTP synchronizesthe credential.

If a CheckOTP call fails to validate a credential, the CheckOTP call does not increment the credential’s failed validationcount. If a CheckOTP call synchronizes a credential, it does not change the credential state. You cannot use theCheckOTP API for credentials in a new state or inactive state.


NOTE

The CheckOTP API call is for administrative purposes only, and is not a substitute for the Validate andSynchronize APIs.

Do not use the CheckOTP API for normal authentication and synchronization. The CheckOTP API overrides therequirement (in the Validate and Synchronize APIs) that a credential is Enabled.

Because CheckOTP authenticates and synchronizes locked credentials, you should only use it only when you can verifythe identity of an end user. For normal authentication and synchronization, use the Validate and Synchronize APIs.

• Request for checking a security code on a locked credential• Response for checking a security code on a locked credential• CheckOTP error codes

Request for checking a security code on a locked credentialCheckOTP input fields provides details about the CheckOTP input fields. Send the request to:


50



Table 29: CheckOTP input fields



OTP1 Y String The VIP Service Web Service checks the security codes(OTPs) against the credential ID to verify the validity of thecredential.The first security code is mandatory, and the secondsecurity code entry is optional. If a second security code issent, the web server synchronizes the credential.

OTP2 N String The VIP Service Web Service checks the security codes(OTPs) against the credential ID to verify the validity of thecredential. The first security code is mandatory, and thesecond security code is optional. If a second security codeis sent, the web server synchronizes the credential.

See Sample CheckOTP SOAP XML request.

Sample CheckOTP SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>







<SOAP-ENV:Body>

<ns1:CheckOTP Version="3.1" Id="BJFF6556">


<ns1:OTP1>189440</ns1:OTP1>

<ns1:OTP2>670438</ns1:OTP2>

</ns1:CheckOTP>

</SOAP-ENV:Body>


Response for checking a security code on a locked credentialCheckOTP output fields provides details about the CheckOTP output fields.

Table 30: CheckOTP output fields


ReasonCode Y hexBinary If the request to check the security code is unsuccessful,the ReasonCode provides the reason.

StatusMessage Y String States whether the security code check was successful.

51







See Sample CheckOTP SOAP XML response.

Sample CheckOTP SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>


<Body>

<CheckOTPResponse RequestId="BJFF6556" Version="3.1"


<Status>



</Status>







</CheckOTPResponse>

</Body>

</Envelope>

CheckOTP error codesThis section lists the error codes you may encounter using the CheckOTP API.


52



or format.

4923: The OTP you provided is within the Sync Window, but outside the

Look Ahead Window. This operation requires a second consecutive OTP


4995: Operation not allowed on new token











Getting information about a credentialYou can get information about a credential with the getTokenInformation API. The getTokenInformation API described inthis section does not apply to SMS OTP, Voice OTP, or Service-generated OTP credentials.

• About the SMS OTP credential APIs• About the Voice OTP credential APIs• About the Service-generated OTP credential APIs

Use the getTokenInformation API to get detailed information about a credential, such as:

• the credential stateSee Credential states.

• the credential type• the credential expiration date• the last time an API call was made to the VIP Service Web Services about the credential• detailed information about the credential, such as credential form factor and whether the security code is generated by

hardware or software.

The request requires only the credential ID.

• Request for getting information about a credential• Response for getting information about a credential• getTokenInformation error codes

Request for getting information about a credentialgetTokenInformation input fields provides details about the getTokenInformation input field. Send the request to:


Table 31: getTokenInformation input fields



53



See Sample getTokenInformation SOAP XML request.

Sample getTokenInformation SOAP XML request<?xml version="1.0" encoding="UTF-8" ?>







<SOAP-ENV:Body>

<ns1:getTokenInformation Version="3.1" Id="ACGC0670">


</ns1:getTokenInformation>

</SOAP-ENV:Body>


Response for getting information about a credentialThe getTokenInformation response is an array of a complex type. getTokenInformation output fields shows the informationyou see in the array.

Table 32: getTokenInformation output fields


ReasonCode Y hexBinary If a request to retrieve a security code expiration isunsuccessful, the ReasonCode provides the reason.

StatusMessage Y String States whether the temporary security code expiration wassuccessfully retrieved.

TokenId Y String Shows a unique string of numeric characters identifying thecredential.

TokenKind Y String Shows whether the credential is a software credential orhardware credential.

Adapter Y String Shows the credential type. Each credential is one of sixcredential types:• OATH_EVENT_BASIC• OATH_EVENT_ADVANCED_1• OATH_EVENT_ADVANCED_2• VASCO_TIME• OATH_TIME• SMS_OTPSERVER_OTP

TokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,Locked, or New).See Credential states.

ExpirationDate Y dateTime Shows the credential expiration date.TempPasswordExpirationDateN dateTime Shows the temporary security code expiration date (if

there is a temporary security code associated with thecredential).See Setting and managing temporary security codes.

54



TempPasswordOneTimeUse N boolean Indicates whether a temporary security code is for one-timeuse only.

LastUpdate Y dateTime Shows the last time that the VIP Service Web Servicesupdated the credential.

Owner N boolean Shows whether the API call came from the same party thatissued the credential.

NumberofParties Y number Indicates the number of VIP members with which thiscredential has (ever) been assigned.See Using Network Intelligence.

TokenState Y Array Indicates the credential state at all VIP Service networkproviders for the selected credential.See Using Network Intelligence.

GlobalFailureCount Y number Number of consecutive times a credential validation hasfailed across the VIP Service network.See Using Network Intelligence.





See Sample getTokenInformation SOAP XML response.

Sample getTokenInformation SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>


<Body>

<getTokenInformationResponse RequestId="FECG8273" Version="3.1"


<Status>



</Status>

55


<TokenInformation>

<TokenId>VSMB21481289</TokenId>

<TokenKind>SOFTWARE</TokenKind>

<Adapter>OATH_EVENT_BASIC</Adapter>

<TokenStatus>ENABLED</TokenStatus>


<TempPasswordExpirationDate>2008-08-14T13:48:06.000-07:00</Temp

PasswordExpirationDate>

<TempPasswordOneTimeUse>true</TempPasswordOneTimeUse>

<LastUpdate>2008-08-11T13:48:39.000-07:00</LastUpdate>

<Owner>true</Owner>

</TokenInformation>

<NetworkIntelligence>

<NumberOfParties>1</NumberOfParties>

<TokenState type="ENABLED">

<Total>1</Total>

</TokenState>

<GlobalFailureCount>0</GlobalFailureCount>

</NetworkIntelligence>







</getTokenInformationResponse>

</Body>

</Envelope>

getTokenInformation error codesThis section lists the error codes you may encounter using the getTokenInformation API.












Performing operations on behalf of othersThe AuthorizerAccountId element is an optional element that can be included with any operation. The AuthorizerAccountIdelement is used by a parent account (such as a reseller) to send operations on behalf of a child account (such as acustomer). The element contains a unique jurisdiction identifier for the child account (the jurisdiction identifier is availablefrom the VIP Manager).

56


The parent account uses its own certificate in the operation request to authenticate the request to VIP AuthenticationService.

• Request using the AuthorizerAccountId element• Response to request using the AuthorizerAccountId element

Request using the AuthorizerAccountId elementThe following is a SetTemporaryPwdExpiration request which includes the AuthorizerAccountId element. This request by aparent account modifies the temporary password expiration date for a credential issued under the child account. The childaccount is identified by the jurisdiction identifier sent in the AuthorizerAccountId element.


<soapenv:Envelope




<soapenv:Body>

<SetTemporaryPwdExpiration

xmlns="https://schemas.vip.symantec.com/2006/08/vipservice"

xmlns:ds="http://www.w3.org/2000/09/xmldsig#"


xsi:schemaLocation="https://schemas.vip.symantec.com/2006/08/

vipservice" Version="3.1" Id="1234abcd">

<AuthorizerAccountId>72480532</AuthorizerAccountId>

<TokenId>VSME25439494</TokenId>


</SetTemporaryPwdExpiration>

</soapenv:Body>

</soapenv:Envelope>

Response to request using the AuthorizerAccountId elementThe following is the sample response to a SetTemporaryPwdExpiration request using the AuthorizerAccountId element.This response indicates that the parent account successfully modified a temporary password expiration date for acredential issued under the specified child account.

The following is the sample response to a SetTemporaryPwdExpiration

request using the AuthorizerAccountId element. This response indicates

that the parent account successfully modified a temporary password

expiration date for a credential issued under the specified child account.



<Body>

<SetTemporaryPwdExpirationResponse RequestId="1234abcd" Version=

"3.1"


<Status>



</Status>

</SetTemporaryPwdExpirationResponse>

</Body>

</Envelope>

57


Using Network IntelligenceVIP Service Network Intelligence provides detailed information for registered credentials. VIP Service network intelligencedisplays the selected credential’s activity across the VIP Service network as follows:

• Reason codes for disabled or deactivated credentialsSee Reason codes for a disabled and deactivated credential.

• Global failed count for the selected credentialSee Global failed count.

• Report the credential status across the network using the Network Intelligence APIsSee Network Intelligence APIs.

Reason codes for a disabled and deactivated credentialThe credentials status and reason code are displayed on the Find a Credential page of the Management Console. Thisfeature can be used to decide if the token is compromised, or suspect, or being fraudulently used, and to provide a reasonwith requests to disabling or deactivating the token.

Additionally, you can retrieve the previously set reason by issuing a getTokenInformation call for the token.

The available reason codes are:

• Unspecified - the default reason when no reason is specified• Lost - user has reported the credential as lost, broken, or destroyed (for example, the user no longer has the credential

and is never getting it back, but does not suspect it is in the hands of an attacker)• Temporarily Unavailable - user has reported a credential temporarily forgotten or misplaced (for example, the user

does not currently have the credential, but will get it back)• Stolen - user has reported the credential as stolen Returned - the issuer received the credential from the user (for

example, issuer confirms that it is in possession of the credential and not lost or in the hands of an attacker)• Canceled - user has removed the credential from their account or terminated the relationship with the VIP Service

network provider.

Global failed countA credentials state is provided to all VIP Service network providers for the selected credential. This feature displays thestate of a credential that has been reported lost or stolen (or any of the other reason codes) at another providers site. Asample of the data returned is displayed in Status across the network.

Table 33: Status across the network

Status Reason Number

Enabled 5Locked 1Disabled Lost 3Disabled Canceled 1Inactive Unspecified 2

The columns display the following:

• The credential’s status across the network (Enabled, Locked, Disabled and Inactive).• The reason the credential is in its displayed state (Enabled, Disabled, or Inactive).• The number of providers that this credential registered at. This data is returned for every state except NEW.

58


In this example the credential has been:

• Enabled with five providers• Locked with one provider• Disabled (Reason = Lost) with three providers• Disabled (Reason = Canceled) with one provider• Deactivated (Reason = Unspecified) with two providers

Network Intelligence APIsVIP Service’s Validate and getTokenInformation API can be called to validate a credential or get detailed credentialinformation.

• Validate for Network Intelligence• Get Token Information with Network Intelligence

Network Intelligence API prerequisites lists the prerequisites for Validate and getTokenInformation APIs.

Table 34: Network Intelligence API prerequisites


Validate Validates the security code. Validate for Network IntelligencegetTokenInformation withNetwork Intelligence

Gets information about a specific credential and activation statuswith other service members.

Get Token Information withNetwork Intelligence

Validate for Network IntelligenceUse the Validate API to validate information for a credential.

Sample Validate response



<Body>

<ValidateResponse RequestId="DGGE4550" Version="3.1"


<Status>



</Status>

<NetworkAlert>true</NetworkAlert>







</ValidateResponse>

</Body>

</Envelope>

59


Get Token Information with Network IntelligenceUse the getTokenInformation API to retrieve detailed information for a registered credential.

Sample getTokenInformation response



<Body>

<getTokenInformationResponse RequestId="CCFD6815" Version="3.1"


<Status>



</Status>

<TokenInformation>

<TokenId type="SMS">3424567</TokenId>


<Adapter>SMS_OTP</Adapter>

<TokenStatus>DISABLED</TokenStatus>



<Owner>true</Owner>

<ReportedReason>Stolen</ReportedReason>

</TokenInformation>







</getTokenInformationResponse>

</Body>

</Envelope>

60


SMS OTP credential APIs

The VIP Service includes APIs specific to SMS credential types. Use these APIs for all the administrative functions thatare needed to manage SMS OTP credentials for your end users. You must have already purchased SMS OTP credentialsfrom Symantec to use these APIs.

VIP can generate a security code and deliver it to a user’s mobile phone through the Short Message Service (SMS). Yourapplication registers the phone number with VIP, which then validates the security code.

All security codes that are returned for SMS OTP credentials expire after a set time period. Additionally, SMS OTPcredentials do not lock. When the Security Code Expiration or Maximum Validation Failures value is exceeded, the currentsecurity code is automatically invalidated. When a new security code is requested, the Security Code Expiration andMaximum Validation Failures counters are reset.

By default, the Security Code Expiration is set to 10 minutes and the Maximum Validation Failures is set to 10. Bothvalues can be configured in VIP Manager (select Credential Security Settings under Customer Credential Management,then click Change Settings for SMS/Voice/Service Based). SMS OTP, Voice OTP, and Service-generated OTPcredentials share the same configuration settings. Configuring Security Code Expiration and Maximum Validation Failuresfor one credential type configures them for all three.

• Registering an SMS OTP credential• Using the SMS credential• SMS OTP credential APIs• Additional SMS OTP APIs• Unlocking SMS OTP credentials• SMS message templates

Registering an SMS OTP credentialAny mobile phone can be used as a credential (see Credential state changes) if it is registered with VIP Web Services. Touse a mobile phone as a credential, use the following API calls:

• Register the phone number.See Registering an SMS OTP credential.

• ActivateToken for SMS OTP to activate the phone.See Activating an SMS OTP credential.

After being activated, you can use and manage an SMS OTP credential like any other credential:

• Using the SMS credential.• Additional SMS OTP APIs.

Using the SMS credentialAfter the SMS OTP credential is registered and activated, use the credential by sending and validating security codesusing the following APIs:

• SendOTP sends a security code to the mobile phone.See SendOTP for SMS OTP.

• Validate verifies that the security code is sent to the phone.See Validate for SMS OTP.

61


SMS OTP credential APIsSMS OTP credential APIs lists each SMS OTP Credential API and its prerequisites, and cross-references the topics thatcontain additional information and code samples.

Table 35: SMS OTP credential APIs


SMS OTP Credential APIsRegister for SMS OTP Registers a phone number in VIP. Registering an SMS OTP

credentialActivateToken for SMS OTP Activates a mobile device as a credential. Activating an SMS OTP

credentialSendOTP for SMS OTP Sends a security code by SMS to a registered phone number. SendOTP for SMS OTPValidate for SMS OTP Validates the information about a specific SMS OTP credential’s

security code.Validate for SMS OTP

Additional SMS OTP APIsDeactivateToken for SMS OTP Changes the SMS OTP credential’s state to inactive. DeactivateToken for SMS OTPEnableToken for SMS OTP Reactivates an SMS OTP credential that you have disabled. If you

disable a credential, the user cannot use the credential until anadministrator sets it back to an Enabled state.

EnableToken for SMS OTP

DisableToken for SMS OTP Disables an SMS OTP credential. DisableToken for SMS OTPUnlockToken for SMS OTP Changes an SMS OTP credential state from Locked to Enabled. Unlock an SMS OTP credentialGetTokenInformation for SMSOTP

Gets the information about an SMS OTP credential. Getting Token Information forSMS OTP credentials

SendTemporaryPassword forSMS OTP

Sends a generated temporary security code by SMS to aregistered phone number.

Sending a temporary securitycode

Registering an SMS OTP credentialUse the Register API to register a new SMS OTP credential (see Credential state changes):

• Sample register for SMS OTP request• Sample Register for SMS OTP response• Register error codes

Sample register for SMS OTP requestRegister for SMS OTP input fields provides details about the Register for SMS OTP input fields. Send the request to:

https://services-auth.vip.symantec.com/prov/soap

62



Table 36: Register for SMS OTP input fields


TokenId Y String Specifies the phone number that identifies the credential tothe VIP Web Services. Do not use spaces or dashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456To specify a phone number, set the attribute type for theTokenId element to SMS. For example:TokenId type="SMS"

Message N String Specifies the SMS message template that is sent to aphone number.Messages must be less than 160 characters.If no Message template is supplied, the default messagetemplate that is configured in VIP Manager is used.

DeliverOTP N Boolean Specifies whether the security code is delivered to a phonethrough SMS. By default (if this element is not specified inthe request), the security code is delivered. If the value forthis element is false, the security code is not delivered.

SMSFrom N String This field is deprecated.

See Sample SOAP XML Register request.

Sample SOAP XML Register request


<SOAP-ENV:Envelope







<SOAP-ENV:Body>

<ns1:Register Version="3.1" Id="1234abcd">

<ns1:TokenId type="SMS">16505551212</ns1:TokenId>

<ns1:DeliverOTP>true</ns1:DeliverOTP>

<ns1:SMSDeliveryInfo>

<ns1:Message>Use security code _OTP_ to activate your phone.

</ns1:Message>


</ns1:Register>

</SOAP-ENV:Body>


Sample Register for SMS OTP responseRegister for SMS OTP output fields provides details about the Register for SMS OTP output fields.

63


Table 37: Register for SMS OTP output fields


ReasonCode Y hexBinary If a register request is unsuccessful, the ReasonCodeprovides the reason.See Register error codes.

StatusMessage Y String States whether the credential was successfully registered.

See:

• Sample SOAP XML response• Register error codes

Sample SOAP XML response



<Body>

<RegisterResponse RequestId=" EICG5753" Version="3.1"


<Status>



</Status>

</RegisterResponse>

</Body>

</Envelope>

Register error codesThis section lists the error codes you may encounter using the Register API.









4e0a: Token orders for this token type already fulfilled or expired


4e1a: Unable to send SMS to given number through gateway

4e1b: Phone number has already been activated

Activating an SMS OTP credentialThe ActivateToken for SMS OTP API is called when a newly registered SMS OTP credential requires activation (seeCredential state changes):

64


• Sample ActivateToken for SMS OTP request• Sample ActivateToken for SMS OTP response• ActivateToken for SMS OTP error codes

Sample ActivateToken for SMS OTP requestActivateToken for SMS OTP input fields provides details about the ActivateToken for SMS OTP input fields. Send therequest to:


Table 38: ActivateToken for SMS OTP input fields



OTP1 N String The VIP Web Service checks any security codes againstthe credential ID to verify the validity of the credential.

See Sample SOAP XML request.

Sample SOAP XML request








<SOAP-ENV:Body>

<ns1:ActivateToken Version="3.1" Id="1234abcd">


<ns1:OTP1>897130</ns1:OTP1>


</SOAP-ENV:Body>


Sample ActivateToken for SMS OTP responseActivateToken for SMS OTP output fields lists the ActivateToken for SMS OTP output fields.

65



Table 39: ActivateToken for SMS OTP output fields


ReasonCode Y hexBinary If an activation request is unsuccessful, the ReasonCodeindications why the operation failed.

StatusMessage Y String States whether the credential was successfully activated.SameInitialState N Boolean States whether the credential changed states.

See:

• Sample SOAP XML response• ActivateToken for SMS OTP error codes




<Body>

<ActivateTokenResponse RequestId="EHBE4660" Version="3.1"


<Status>



</Status>



</Body>

</Envelope>

ActivateToken for SMS OTP error codesThis section lists the error codes you may encounter using the ActivateToken for SMS OTP API.












4e1d: OTP needs to be supplied for a phone number in a new state



4e16: Phone number was not previously registered for this account

4f05: This VIP credential or VIP credential type is not supported for this

account.

66


SendOTP for SMS OTPAfter registering and activating the phone number, use the SendOTP API to send a security code to the phone number.

• Sample SendOTP for SMS OTP request• Sample SendOTP for SMS OTP response• SendOTP for SMS OTP error codes

Sample SendOTP for SMS OTP requestSendOTP for SMS OTP input fields provides details about the SendOTP for SMS OTP input field. Send the request to:


Table 40: SendOTP for SMS OTP input fields



See:

• Sample SOAP XML request• SendOTP for SMS OTP error codes









<SOAP-ENV:Body>

<ns1:SendOTP Version="3.1" Id="JGBJ7818">


</ns1:SendOTP>

</SOAP-ENV:Body>


Sample SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>


<Body>

<SendOTPResponse RequestId="JGBJ7818" Version="3.1"

67




<Status>



</Status>

</SendOTPResponse>

</Body>

</Envelope>

See SendOTP for SMS OTP error codes.

Sample SendOTP for SMS OTP responseSendOTP for SMS OTP output fields provides details about the SendOTP for SMS OTP output fields.

Table 41: SendOTP for SMS OTP output fields


ReasonCode Y hexBinary If the SendOTP request is unsuccessful, the ReasonCodewhy the operation failed.

StatusMessage Y String States whether the SendOTP request was successfullycompleted.

See:

• Sample SOAP XML response• SendOTP for SMS OTP error codes




<Body>

<SendOTPResponse RequestId="JGBJ7818" Version="3.1"


<Status>



</Status>

</SendOTPResponse>

</Body>

</Envelope>

See SendOTP for SMS OTP error codes.

SendOTP for SMS OTP error codesThis section lists the error codes you may encounter using the SendOTP for SMS OTP API.





68








4e17: The phone number has been deactivated by the carrier; the number must

be registered again




Validate for SMS OTPUpon receipt of the security code from the VIP, validate the phone number using the Validate for SMS OTP API toauthenticate the credential.

When you send a Validate call, the VIP Web Services check the validity of the security code, and return a response. Thesecurity code expires after a set period of time. If you request a new security code, the previous security code expiresautomatically.

• Sample Validate for SMS OTP request• Sample Validate for SMS OTP response• Validate for SMS OTP error codes

Validate for SMS OTP requestValidate for SMS OTP input fields provides details about the Validate for SMS OTP input fields. Send the request to:


Table 42: Validate for SMS OTP input fields



OTP Y String A one-time password (OTP) is the security code generatedusing the credential. VIP checks the security code againstthe credential ID to verify the validity of the credential.

See Sample Validate for SMS OTP SOAP XML request.

Sample Validate for SMS OTP SOAP XML request



envelope/"; xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/";

69



xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";

xmlns:xsd="http://www.w3.org/2001/XMLSchema";

xmlns:ns3="http://www.w3.org/2000/09/xmldsig#";

xmlns:ns1="https://schemas.vip.symantec.com/2006/08/vipservice">;

<SOAP-ENV:Body>

<ns1:Validate Version="3.1" Id="1234abcd">



</ns1:Validate>

</SOAP-ENV:Body>


Validate for SMS OTP responseValidate for SMS OTP output fields provides details about the Validate for SMS OTP output fields.

Table 43: Validate for SMS OTP output fields


ReasonCode Y hexBinary If the Validate request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the Validate request was successfullycompleted.





See:

• Sample Validate for SMS OTP SOAP XML response• Validate for SMS OTP error codes

70


Sample Validate for SMS OTP SOAP XML response


<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">;

<Body>

<ValidateResponse RequestId="IFEI4425" Version="3.1"

xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">;

<Status>

<ReasonCode>4E16</ReasonCode>

<StatusMessage>Phone number has not been previously registered for

this account.</StatusMessage>

</Status>



<FormFactor>SMS</FormFactor>


<OtpGeneratedBy>SERVER</OtpGeneratedBy>


</ValidateResponse>

</Body>

</Envelope>

Validate for SMS OTP error codesThis section lists the error codes you may encounter using the Validate for SMS OTP API.














Additional SMS OTP APIsYou can perform the following additional operations for a registered phone number:

• Deactivate the credential with the DeactivateToken for SMS OTP API.See DeactivateToken for SMS OTP.

• Enable the credential with the EnableToken for SMS OTP API.See EnableToken for SMS OTP.

• Disable the credential with the DisableToken for SMS OTP API.SeeDisableToken for SMS OTP.

• Retrieve information about the credential with the GetTokenInformation for SMS OTP API.

71


See Getting Token Information for SMS OTP credentials.• Send a temporary security code to the phone when the user loses their security code with the

SendTemporaryPassword for SMS OTP API.See Sending a temporary security code.

DeactivateToken for SMS OTPUse the DeactivateToken for SMS OTP API to deactivate an SMS OTP credential. If the deactivation is successful, thecredential is deactivated.

• Sample DeactivateToken for SMS OTP request• Sample DeactivateToken for SMS OTP response• DeactivateToken for SMS OTP error codes

See Activating an SMS OTP credential.

Sample DeactivateToken for SMS OTP requestDeactivateToken for SMS OTP input fields provides details about the DeactivateToken for SMS OTP input fields. Send therequest to:


Table 44: DeactivateToken for SMS OTP input fields



Reason N String To specify the reason for deactivating the token.

See Sample DeactivateToken for SMS OTP request.

Sample DeactivateToken for SMS OTP SOAP XML request








<SOAP-ENV:Body>

<ns1:DeactivateToken Version="3.1" Id="HJBA0766">




</SOAP-ENV:Body>

72




DeactivateToken for SMS OTP responseDeactivateToken for SMS OTP output fields lists the DeactivateToken for SMS OTP output fields.

Table 45: DeactivateToken for SMS OTP output fields


ReasonCode Y hexBinary If the deactivation request is unsuccessful, theReasonCode provides the reason.

StatusMessage Y String States whether the credential was successfully deactivated.SameInitialState N Boolean States whether the credential changed states.

See Sample DeactivateToken for SMS OTP SOAP XML response.

Sample DeactivateToken for SMS OTP SOAP XML response



<Body>

<DeactivateTokenResponse RequestId="HJBA0766" Version="3.1"


<Status>



</Status>



</Body>

</Envelope>

DeactivateToken for SMS OTP error codesThis section lists the error codes you may encounter using the DeactivateToken for SMS OTPAPI.












73


EnableToken for SMS OTPUse the EnableToken for SMS OTP API to enable a previously disabled SMS OTP credential (see Credential statechanges). If the request is successful, the credential is Enabled.

• EnableToken for SMS OTP request• EnableToken for SMS OTP response• EnableToken for SMS OTP error codes

See DisableToken for SMS OTP.

EnableToken for SMS OTP requestEnableToken for SMS OTP input fields provides details about the EnableToken for SMS OTP input fields. Send therequest to:


Table 46: EnableToken for SMS OTP input fields



See Sample EnableToken for SMS OTP SOAP XML request.



<SOAP-ENV:Envelope







<SOAP-ENV:Body>

<ns1:EnableToken Version="3.1" Id="IGEC8036">


</ns1:EnableToken>

</SOAP-ENV:Body>


See Sample EnableToken for SMS OTP SOAP XML response.

74



EnableToken for SMS OTP responseEnableToken for SMS OTP output fields lists the EnableToken for SMS OTP output fields.

Table 47: EnableToken for SMS OTP output fields


ReasonCode Y hexBinary If the enable request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully enabled.SameInitialState N Boolean States whether the credential changed states.

Sample EnableToken for SMS OTP SOAP XML response



<Body>

<EnableTokenResponse RequestId="IGEC8036" Version="3.1"


<Status>



</Status>


</EnableTokenResponse>

</Body>

</Envelope>

EnableToken for SMS OTP error codesThis section lists the error codes you may encounter using the EnableToken for SMS OTP API.











DisableToken for SMS OTPUse the DisableToken for SMS OTP API to disable an SMS OTP credential (see Credential state changes). If the requestis successful, the credential is Disabled.

• DisableToken for SMS OTP request• DisableToken for SMS OTP response• DisableToken for SMS OTP error codes

75


See EnableToken for SMS OTP.

DisableToken for SMS OTP requestDisableToken for SMS OTP input fields provides details about the DisableToken for SMS OTP input fields. Send therequest to:


Table 48: DisableToken for SMS OTP input fields



Reason N String Specifies the reason for disabling the credential.

Sample DisableToken for SMS OTP SOAP XML request








<SOAP-ENV:Body>

<ns1:DisableToken Version="3.1" Id="EBFC3461">


<ns1:Reason>Stolen</ns1:Reason>

</ns1:DisableToken>

</SOAP-ENV:Body>


DisableToken for SMS OTP responseEnableToken for SMS OTP output fields lists the DisableToken for SMS OTP output fields.

Table 49: EnableToken for SMS OTP output fields


ReasonCode Y hexBinary If the disable request is unsuccessful, the ReasonCodeindicates why the request failed.

StatusMessage Y String States whether the credential was successfully disabled.SameInitialState N Boolean States whether the credential changed states.

76



Sample DisableToken for SMS OTP SOAP XML response



<Body>

<DisableTokenResponse RequestId="EBFC3461" Version="3.1"


<Status>



</Status>



</Body>

</Envelope>

DisableToken for SMS OTP error codesThis section lists the error codes you may encounter using the DisableToken for SMS OTP API.











Unlocking SMS OTP credentialsCredentials become locked when they exceed the configured number of allowed continuous validation failures. You canunlock users' credentials with the UnlockToken API. You must verify that a user is in possession of their credential beforeyou unlock it. First, verify the user’s identity through some other means, and then request a security code from the user.To check the security code, use the CheckOTP API. If the CheckOTP call succeeds, then make an UnlockToken call.

• Unlock an SMS OTP credential• Getting Token Information for SMS OTP credentials• Sending a temporary security code for SMS OTP

See Checking security codes on locked credentials.

Unlock an SMS OTP credentialUse the UnlockToken API to unlock SMS OTP credentials that have become locked. Unlocking an SMS OTP credentialchanges the state of the credential from Locked to Enabled and makes it ready for use (see Credential state changes).

• Unlock for SMS OTP request• Unlock for SMS OTP response• UnlockToken for SMS OTP error codes

77


Unlock for SMS OTP requestUnlockToken for SMS OTP input fields provides details about the UnlockToken for SMS OTP input field. Send the requestto:


Table 50: UnlockToken for SMS OTP input fields



See Sample Unlock for SMS OTP SOAP XML request.

Sample Unlock for SMS OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>


<ns1:TokenId type="SMS">VSMB57361338</ns1:TokenId>

</ns1:UnlockToken>

</SOAP-ENV:Body>

Unlock for SMS OTP responseUnlockToken for SMS OTP output fields provides details about the UnlockToken for SMS OTP output fields.

Table 51: UnlockToken for SMS OTP output fields


ReasonCode Y hexBinary If an unlock request is unsuccessful, the ReasonCodeprovides the reason.

StatusMessage Y String States whether the credential was successfully unlocked.SameInitialState N Boolean States whether the credential changed states.

See Sample Unlock for SMS OTP SOAP XML response.

78



Sample Unlock for SMS OTP SOAP XML response



<Body>



<Status>



</Status>



</Body>

</Envelope>

UnlockToken for SMS OTP error codesThis section lists the error codes you may encounter using the UnlockToken API.















Getting Token Information for SMS OTP credentialsUse the GetTokenInformation for SMS OTP credentials API to get information about an SMS OTP credential (seeCredential state changes). If the request is successful, the credential information is displayed.

• GetTokenInformation for SMS OTP request• Sample GetTokenInformation for SMS OTP response• GetTokenInformation for SMS OTP error codes

Sample GetTokenInformation for SMS OTP requestGetTokenInformation for SMS OTP input fields provides details on the GetTokenInformation for SMS OTP input fields.Send the request to:


79



Table 52: GetTokenInformation for SMS OTP input fields



See Sample GetTokenInformation for SMS OTP SOAP XML request.

Sample GetTokenInformation for SMS OTP SOAP XML request


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"






<SOAP-ENV:Body>

<ns1:GetTokenInformation Version="3.1" Id="CCFD6815">


</ns1:GetTokenInformation>

</SOAP-ENV:Body>


Sample GetTokenInformation for SMS OTP responseGetTemporaryPwdExpiration output fields lists the GetTokenInformation for SMS OTP output fields.



ReasonCode Y hexBinary If the request to retrieve information is unsuccessful, theReasonCode provides the reason.

StatusMessage Y String States whether the credential information was successfullyretrieved.

TokenId Y String Shows a unique string of numeric characters identifying theSMS credential.


Adapter Y String Shows the credential type: SMS_OTPTokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,

Locked, or New).See Credential states.

ExpirationDate Y dateTime Shows the credential expiration date.

80



LastUpdate Y dateTime Shows the last time that there was a call to the VIP WebServices for the credential.


ReportedReason N String Shows the reported reason for this token ID.

See Sample GetTokenInformation for SMS OTP SOAP XML response.

Sample GetTokenInformation for SMS OTP SOAP XML response



<Body>

<GetTokenInformationResponse RequestId="CCFD6815" Version="3.1"


<Status>



</Status>

<TokenInformation>

<TokenId type="SMS">3424567</TokenId>


<Adapter>SMS_OTP</Adapter>




<Owner>true</Owner>

<ReportedReason>Stolen</ReportedReason>

</TokenInformation>

</GetTokenInformationResponse>

</Body>

</Envelope>

GetTokenInformation for SMS OTP error codesThis section lists the error codes you may encounter using the GetTokenInformation for SMS OTP API.










4bf1: This operation does not support this credential type

81


Sending a temporary security code for SMS OTPIf a user’s credential is lost or stolen, use the SendTemporaryPassword for SMS API to generate and send a temporarysecurity code to the user’s phone number. The system-generated, temporary security code is sent using SMS, and is validfor one use only. The temporary security code must be used before the specified expiration time (up to seven days).

To complete this operation, you must provide the user name and password for your account on the SMS Gateway.

• SendTemporaryPassword for SMS OTP request• SendTemporaryPassword for SMS OTP response• SendTemporaryPassword for SMS OTP error codes

SendTemporaryPassword for SMS OTP requestUnlockToken for SMS OTP input fields provides details about the SendTemporaryPassword for SMS OTP input fields.Send the request to:


Table 54: UnlockToken for SMS OTP input fields



PhoneNumber Y for SMS OTP String The phone number to receive the password if using SMSOTP only. Do not use spaces or dashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456

ExpirationDate N dateTime The temporary security code expiration date (maximum ofseven days). If no date is provided, the default expirationperiod is used to calculate the password expiration.

SMSFrom N String This input field is deprecated.Message N String Specifies the SMS message template that is sent to a

phone number.Messages must be less than 160 characters.Messages support UTF-8 characters.If no Message template supplied, then the default messagetemplate that is configured in VIP Manager is used.

See Sample SendTemporaryPassword for SMS OTP SOAP XML request.

Sample SendTemporaryPassword for SMS OTP SOAP XML request



envelope/"

82








<SOAP-ENV:Body>

<ns1:SendTemporaryPassword Version="3.1" Id="AIAC6061">


<ns1:PhoneNumber>16505551212</ns1:PhoneNumber>

<ns1:GatewayAcctInfo>

<ns1:Id>1234</ns1:Id>

<ns1:Password>abcdef</ns1:Password>

</ns1:GatewayAcctInfo>



<ns1:Message>Your one-time temporary password is _OTP_.

</ns1:Message>

</ns1:SMSDeliveryInfo>

</ns1:SendTemporaryPassword>

</SOAP-ENV:Body>


SendTemporaryPassword for SMS OTP responseUnlockToken for SMS OTP output fields provides details about the SendTemporaryPassword for SMS OTP output fields.



ReasonCode Y hexBinary If the request to set a temporary security code isunsuccessful, the ReasonCode indicates why the operationfailed.


See Sample SendTemporaryPassword for SMS OTP SOAP XML response.

Sample SendTemporaryPassword for SMS OTP SOAP XML response



<Body>

<SendTemporaryPasswordResponse RequestId="BBEB4255" Version="3.1"


<Status>



</Status>

</SendTemporaryPasswordResponse>

</Body>

</Envelope>

83


SendTemporaryPassword for SMS OTP error codesThis section lists the error codes you may encounter using the SendTemporaryPassword for SMS OTP API.

















SMS message templatesA message template can be sent as part of a SendTemporaryPassword for SMS OTP, SendOTP for SMS OTP, orRegister for SMS OTP XML request. This message template overrides the configured or the default message template.This message template is used only for the single request, and then the default or configured message template isrestored.

The following APIs have default message templates that can be customized:

• Register for SMS OTP• SendOTP for SMS OTP• SendTemporaryPassword for SMS OTP

Any message for the APIs can be customized using VIP Manager. After a message is customized, the VIP Web Serviceuses the customized message. If the message template is not customized, the VIP Web Service uses the defaulttemplate.

Customized messages require the following parameters:

• Have “_OTP_” as part of the message. The security code replaces _OTP_ in the SMS message before the message issent to the phone.

• The message must be less than 160 characters.• UTF-8 characters can be used to create a message template. Only ASCII is supported for US-based phones.

If you change a default message, the VIP Web Service uses the modified message as the default. The original defaultmessage is not available after it is modified.

Default message types for the SMS message templateDefault message types lists the default message types for the SMS message template that are provided by the VIP WebService. You can see the default message in VIP Manager.

84


Table 56: Default message types

Message Type Default Message Template

REGISTER Use Symantec VIP security code _OTP_ to register your phone.TEMP_PASSWORD Your Symantec VIP temporary security code is _OTP_.SERVICE Your Symantec VIP security code is _OTP_.

Customized SMS OTP message requestThe following samples are the customized XML requests for the following:

• Register for SMS OTP• SendOTP for SMS OTP• SendTemporaryPassword for SMS OTP

Register for SMS OTPThe following is the Register for SMS OTP request with an override template:








<SOAP-ENV:Body>

<ns1:Register Id="ipsita1234" Version="3.1"




<ns1:Message>Your Security code is _OTP_</ns1:Message>


</ns1:Register>

</SOAP-ENV:Body>


SendOTP for SMS OTPAfter registering and activating the phone number, use the SendOTP API to send a security code to the phone number.

• Sample SendOTP for SMS OTP request• Sample SendOTP for SMS OTP response• SendOTP for SMS OTP error codes

SendTemporaryPassword for SMS OTPThe following is the SendTemporaryPassword for SMS OTP request with an override template:




85






<SOAP-ENV:Body>

<ns1:SendTemporaryPassword Id="1234abcd" Version="3.1"



<ns1:PhoneNumber>16505551212</ns1:PhoneNumber>

<ns1:GatewayAcctInfo>

<ns1:ID>0000</ns1:ID>

<ns1:Password>abcdefgh</ns1:Password>

</ns1:GatewayAcctInfo>

<ns1:ExpirationDate>2008- 02-21T14:30:01-08:00</ns1:Expiration

Date>


<ns1:Message>Your one-time temporary password is _OTP_.</ns1:Message>


</ns1:SendTemporaryPassword>

</SOAP-ENV:Body>


86


Voice OTP credential APIs

The VIP Service includes APIs specific to Voice credential types. Use these APIs for all the administrative functionsthat are needed to manage Voice OTP credentials for your end users. You must have already purchased Voice OTPcredentials from Symantec to use these APIs.

VIP can generate a security code and deliver it to a user’s phone as a voice message. Your application registers thephone number with VIP, which then validates the security code. By default, VIP uses Symantec's voice prompts inEnglish. For additional voice prompts (for example, in other languages or customized for your organization), contact yourSymantec representative.

All security codes that are returned for Voice OTP credentials expire after a set time period. Additionally, Voice OTPcredentials do not lock. When the Security Code Expiration or Maximum Validation Failures value is exceeded, the currentsecurity code is automatically invalidated. When a new security code is requested, the Security Code Expiration andMaximum Validation Failures counters are reset.


• Registering a Voice OTP credential• Using the Voice OTP credential• Voice OTP Credential APIs• Additional Voice OTP APIs• Unlocking Voice OTP credentials• Voice messaging

Registering a Voice OTP credentialAny phone can be used as a credential (see Credential state changes) if it is registered with VIP Web Services. To use aphone as a credential, use the following API calls:

• Register the phone number.See Registering a Voice OTP credential.

• ActivateToken for Voice OTP to activate the phone.SeeSee Activating a Voice OTP credential.

After being activated, you can manage a Voice OTP credential like any other credential.

See Additional Voice OTP APIs.

Using the Voice OTP credentialAfter the Voice OTP credential is registered and activated, use the credential by sending and validating security codesusing the following APIs:

• SendOTP sends a security code to the mobile phone.See SendOTP for Voice OTP.

• Validate verifies that the security code is sent to the phone.See Validate for Voice OTP.

87


Voice OTP Credential APIsVoice OTP credential APIs lists each Voice OTP Credential API and its prerequisites, and cross-references the topics thatcontain additional information and code samples.

Table 57: Voice OTP credential APIs


Voice OTP Credential APIsRegister for Voice OTP Registers a phone number in VIP. Registering a Voice OTP

credentialActivateToken for Voice OTP Activates a mobile device as a credential. Activating a Voice OTP

credentialSendOTP for Voice OTP Sends a security code by voice message to a registered phone

number.SendOTP for Voice OTP

Validate for Voice OTP Validates the information about a specific Voice OTP credential’ssecurity code.

Validate for Voice OTP

Additional Voice OTP APIsDeactivateToken for Voice OTP Changes the Voice OTP credential’s state to inactive. DeactivateToken for Voice OTPEnableToken for Voice OTP Reactivates a Voice OTP credential that you have disabled. If you

disable a credential, the user cannot use the credential until anadministrator sets it back to an Enabled state.

EnableToken for Voice OTP

DisableToken for Voice OTP Disables a Voice OTP credential. DisableToken for Voice OTPUnlockToken for Voice OTP Changes a Voice OTP credential state from Locked to Enabled. Unlock a Voice OTP credentialGetTokenInformation for VoiceOTP

Gets the information about a Voice OTP credential. Getting Token Information forVoice OTP credentials

SendTemporaryPassword forVoice OTP

Sends a generated temporary security code by voice message toa registered phone number.

Sending a temporary securitycode for Voice OTP

Registering a Voice OTP credentialUse the Register API to register a new Voice OTP credential (see Credential state changes).

• Register for Voice OTP request• Sample Register for Voice OTP response• Register for Voice OTP error codes

Register for Voice OTP requestRegister for Voice OTP input fields provides details about the Register for Voice OTP input fields. Send the request to:


88



Table 58: Register for Voice OTP input fields


TokenId Y String Specifies the phone number that identifies the credential tothe VIP Web Services. Do not use spaces or dashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456Any appended extension must begin with lower-case "x",followed by any combination of the characters * . , # anddigits 0 to 9.Example: 14885554444x,1112• , (comma) Creates a short delay of approximately 2

seconds• . (period) Creates a longer delay of approximately 5

seconds• * (star) Used by some phone systems to access an

extension• # (pound or hash) Used by some phone systems to

access an extensionTo specify a phone number, set the attribute type for theTokenId element to Voice. For example:TokenId type="Voice"

Account N String Identifies the Symantec Voice Gateway account.See Voice messaging

Language N Language Specifies the language that is used in the voice message.See Voice messaging

DeliverOTP N Boolean Specifies whether the security code is delivered to a phonethrough voice. By default (if this element is not specified inthe request), the security code is delivered. If the value forthis element is false, the security code is not delivered.

See Sample Register for Voice OTP SOAP XML Register request .

Sample Register for Voice OTP SOAP XML Register request



envelope/"



<soapenv:Body>

<Register Id="1234abcd" Version="3.1" xmlns="https://schemas.vip.

symantec.com/2006/08/vipservice">


<ns1:DeliverOTP>true</ns1:DeliverOTP>

<VoiceDeliveryInfo>

<AuthentifyVoiceDeliveryInfo>

<Account>test_accnt</Account>

<Language>en-us</Language>

</AuthentifyVoiceDeliveryInfo>

</VoiceDeliveryInfo>

89


</Register>

</soapenv:Body>

</soapenv:Envelope>

Register for Voice OTP responseRegister for Voice OTP output fields provides details about the Register for Voice OTP output fields.

Table 59: Register for Voice OTP output fields




See Sample Register for Voice OTP SOAP XML response.

Sample Register for Voice OTP SOAP XML response



<Body>

<RegisterResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>

</RegisterResponse>

</Body>

</Envelope>

Register for Voice OTP error codesThis section lists the error codes you may encounter using the Register API.













90


Activating a Voice OTP credentialThe ActivateToken for Voice OTP API is called when a newly registered Voice OTP credential requires activation (seeCredential state changes).

• ActivateToken for Voice OTP request• ActivateToken for Voice OTP response• ActivateToken for Voice OTP error codes

ActivateToken for Voice OTP requestActivateToken for Voice OTP input fields provides details about the ActivateToken for Voice OTP input fields. Send therequest to:


Table 60: ActivateToken for Voice OTP input fields


TokenId Y String Specifies the phone number that identifies the credential tothe VIP Web Services. Do not use spaces or dashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456To specify a phone number, set the attribute type for theTokenId element to Voice. For example:TokenId type="Voice"


See Sample ActivateToken for Voice OTP SOAP XML request.

Sample ActivateToken for Voice OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:ActivateToken Id="1234abcd" Version="3.1" xmlns="https://

schemas.vip.symantec.com/2006/08/vipservice">


<ns1:OTP1>974427</ns1:OTP1>


</SOAP-ENV:Body>


91



Sample ActivateToken for Voice OTP responseActivateToken for Voice OTP output fields lists the ActivateToken for Voice OTP output fields.

Table 61: ActivateToken for Voice OTP output fields




See Sample ActivateToken for Voice OTP SOAP XML response.

Sample ActivateToken for Voice OTP SOAP XML response



<Body>

<ActivateTokenResponse RequestId="1234abcd" Version="3.1" xmlns=


<Status>



</Status>



</Body>

</Envelope>

ActivateToken for Voice OTP error codesThis section lists the error codes you may encounter using the ActivateToken for Voice OTP API.
















4f05: This VIP credential or VIP credential type is not supported

for this account.

92


SendOTP for Voice OTPAfter registering and activating the phone number, use the SendOTP API to send a security code to the phone number.

• SendOTP for Voice OTP request• SendOTP for Voice OTP response• SendOTP for Voice OTP error codes

SendOTP for Voice OTP requestSendOTP for Voice OTP input fields provides details about the SendOTP for Voice OTP input field. Send the request to:


Table 62: SendOTP for Voice OTP input fields


TokenId Y String Specifies the phone number that identifies the credential tothe VIP Web Services. Do not use spaces or dashes.Any appended extension must begin with lower-case "x",followed by any combination of the characters * . , # anddigits 0 to 9.Example: 14885554444x,1112• , (comma) Creates a short delay of approximately 2




access an extensionInclude the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456To specify a phone number, set the attribute type for theTokenId element to Voice. For example:TokenId type="Voice"

Account N String Identifies the Symantec Voice Gateway account.See Voice messaging.

Language N Language Specifies the language that is used in the voice message.See Voice messaging.

See Sample SendOTP for Voice OTP SOAP XML request.

Sample SendOTP for Voice OTP SOAP XML request



envelope/"



<soapenv:Body>

<SendOTP Id="1234abcd" Version="3.1" xmlns="https://schemas.

93



vip.symantec.com/2006/08/vipservice">

<TokenId type="Voice" >16505551212</TokenId>

<VoiceDeliveryInfo>


<Account>test_accnt</Account>




</SendOTP>

</soapenv:Body>

</soapenv:Envelope>

SendOTP for Voice OTP responseSendOTP for Voice OTP output fields provides details about the SendOTP for Voice OTP output fields.

Table 63: SendOTP for Voice OTP output fields




See Sample SendOTP for Voice OTP SOAP XML response.

Sample SendOTP for Voice OTP SOAP XML response



<Body>

<SendOTPResponse RequestId="1234abcd" Version="3.1" xmlns="https://


<Status>



</Status>

</SendOTPResponse>

</Body>

</Envelope>

SendOTP for Voice OTP error codesThis section lists the error codes you may encounter using the SendOTP for Voice OTP API.








94





4e17: The phone number has been deactivated by the carrier; the number

must be registered again




Validate for Voice OTPUpon receipt of the security code from the VIP, validate the phone number using the Validate for Voice OTP API toauthenticate the credential.


• Validate for Voice OTP request• Validate for Voice OTP response• Validate for Voice OTP error codes

Validate for Voice OTP requestValidate for Voice OTP input fields provides details about the Validate for Voice OTP input fields. Send the request to:


Table 64: Validate for Voice OTP input fields




See Sample Validate for Voice OTP SOAP XML request.

Sample Validate for Voice OTP SOAP XML request



envelope/"




95





<SOAP-ENV:Body>

<ns1:Validate Id="1234abcd" Version="3.1" xmlns="https://schemas.vip.




</ns1:Validate>

</SOAP-ENV:Body>


Validate for Voice OTP responseValidate for Voice OTP output fields provides details about the Validate for Voice OTP output fields.

Table 65: Validate for Voice OTP output fields








See Sample Validate for Voice OTP SOAP XML response.

Sample Validate for Voice OTP SOAP XML response



<Body>

<ValidateResponse RequestId="1234abcd" Version="3.1"

96



<Status>



</Status>



<FormFactor>VOICE</FormFactor>




</ValidateResponse>

</Body>

</Envelope>

Validate for Voice OTP error codesThis section lists the error codes you may encounter using the Validate for Voice OTP API.














Additional Voice OTP APIsYou can perform the following additional operations for a registered phone number:

• Deactivate the credential with the DeactivateToken for Voice OTP API.See DeactivateToken for Voice OTP.

• Enable the credential with the EnableToken for Voice OTP API.See EnableToken for Voice OTP.

• Disable the credential with the DisableToken for Voice OTP API.See DisableToken for Voice OTP.

• Retrieve information about the credential with the GetTokenInformation for Voice OTP API.See Getting Token Information for Voice OTP credentials.

• Send a temporary security code to the phone when the user loses their security code with theSendTemporaryPassword for Voice OTP API.See Sending a temporary security code for Voice OTP.

97


DeactivateToken for Voice OTPUse the DeactivateToken for Voice OTP API to deactivate a Voice OTP credential. If the deactivation is successful, thecredential is deactivated.

• DeactivateToken for Voice OTP request• DeactivateToken for Voice OTP response• DeactivateToken for Voice OTP error codes

See Activating a Voice OTP credential.

DeactivateToken for Voice OTP requestDeactivateToken for Voice OTP input fields provides details about the DeactivateToken for Voice OTP input fields. Sendthe request to:


Table 66: DeactivateToken for Voice OTP input fields




See Sample DeactivateToken for Voice OTP SOAP XML request.

Sample DeactivateToken for Voice OTP SOAP XML request



envelope/"




xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" xmlns:ns1="https://


<SOAP-ENV:Body>

<ns1:DeactivateToken Id="1234abcd" Version="3.1" xmlns="https://



<Reason>Unspecified</Reason>


</SOAP-ENV:Body>


98



DeactivateToken for Voice OTP responseDeactivateToken for Voice OTP output fields lists the DeactivateToken for Voice OTP output fields.

Table 67: DeactivateToken for Voice OTP output fields




See Sample DeactivateToken for Voice OTP SOAP XML response.

Sample DeactivateToken for Voice OTP SOAP XML response



<Body>

<DeactivateTokenResponse RequestId="1234abcd" Version="3.1" xmlns=


<Status>



</Status>



</Body>

</Envelope>

DeactivateToken for Voice OTP error codesThis section lists the error codes you may encounter using the DeactivateToken for Voice OTPAPI.












EnableToken for Voice OTPUse the EnableToken for Voice OTP API to enable a previously disabled Voice OTP credential (see Credential statechanges). If the request is successful, the credential is Enabled.

99


• EnableToken for Voice OTP request• EnableToken for Voice OTP response• EnableToken for Voice OTP error codes

See DisableToken for Voice OTP.

EnableToken for Voice OTP requestEnableToken for Voice OTP input fields provides details about the EnableToken for Voice OTP input fields. Send therequest to:


Table 68: EnableToken for Voice OTP input fields



See Sample EnableToken for Voice OTP SOAP XML request.

Sample EnableToken for Voice OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:EnableToken Id="1234abcd" Version="3.1"



</ns1:EnableToken>

</SOAP-ENV:Body>


EnableToken for Voice OTP responseEnableToken for Voice OTP output fields lists the EnableToken for Voice OTP output fields.

100



Table 69: EnableToken for Voice OTP output fields




See Sample EnableToken for Voice OTP SOAP XML response.

Sample EnableToken for Voice OTP SOAP XML response



<Body>

<EnableTokenResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>

<SameInitialState>true</SameInitialState>


</Body>

</Envelope>

EnableToken for Voice OTP error codesThis section lists the error codes you may encounter using the EnableToken for Voice OTP API.











DisableToken for Voice OTPUse the DisableToken for Voice OTP API to disable a Voice OTP credential (see Credential state changes). If the requestis successful, the credential is Disabled.

• DisableToken for Voice OTP request• DisableToken for Voice OTP response• DisableToken for Voice OTP error codes

See EnableToken for Voice OTP.

101


DisableToken for Voice OTP requestDisableToken for Voice OTP input fields provides details about the DisableToken for Voice OTP input fields. Send therequest to:


Table 70: DisableToken for Voice OTP input fields




See Sample DisableToken for Voice OTP SOAP XML request.

Sample DisableToken for Voice OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:DisableToken Id="1234abcd" Version="3.1" xmlns="https://



</ns1:DisableToken>

</SOAP-ENV:Body>


DisableToken for Voice OTP responseDisableToken for Voice OTP output fields lists the DisableToken for Voice OTP output fields.

Table 71: DisableToken for Voice OTP output fields




102



See Sample DisableToken for Voice SOAP XML response.

Sample DisableToken for Voice SOAP XML response



<Body>

<DisableTokenResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>



</Body>

</Envelope>

DisableToken for Voice OTP error codesThis section lists the error codes you may encounter using the DisableToken for Voice OTP API.











Getting Token Information for Voice OTP credentialsUse the GetTokenInformation for Voice OTP credentials API to get information about a Voice OTP credential (seeCredential state changes). If the request is successful, the credential information is displayed.

• GetTokenInformation for Voice OTP request• GetTokenInformation for Voice OTP response• GetTokenInformation for Voice OTP error codes

GetTokenInformation for Voice OTP requestGetTokenInformation for Voice OTP input fields provides details on the GetTokenInformation for Voice OTP input fields.Send the request to:


103



Table 72: GetTokenInformation for Voice OTP input fields



See Sample GetTokenInformation for Voice OTP SOAP XML request.

Sample GetTokenInformation for Voice OTP SOAP XML request

#?xml version="1.0" encoding="UTF-8"?>

#soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/

envelope/"



#soapenv:Body>

#GetTokenInformation Id="1234abcd" Version="3.1" xmlns="https://


#TokenId type="Voice" >16505551212#/TokenId>

#/GetTokenInformation>

#/soapenv:Body>

#/soapenv:Envelope>

GetTokenInformation for Voice OTP responseGetTemporaryPwdExpiration output fields lists the GetTokenInformation for Voice OTP output fields.





TokenId Y String Shows a unique string of numeric characters identifying theVoice credential.


Adapter Y String Shows the credential type: Voice_OTPTokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,



104






See Sample GetTokenInformation for Voice OTP SOAP XML response.

Sample GetTokenInformation for Voice OTP SOAP XML response


Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<Body>

<GetTokenInformationResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>

<TokenInformation>



<Adapter>VOICE_OTP</Adapter>

<TokenStatus>ENABLED</TokenStatus>



<Owner>true</Owner>

</TokenInformation>


</Body>

/Envelope>

GetTokenInformation for Voice OTP error codesThis section lists the error codes you may encounter using the GetTokenInformation for Voice OTP API.











105


Sending a temporary security code for Voice OTPIf a user’s credential is lost or stolen, use the SendTemporaryPassword for Voice OTP API to generate and send atemporary security code to the user’s phone number. The system-generated, temporary security code is sent in a voicemessage, and is valid for one use only. The temporary security code must be used before the specified expiration time (upto seven days).

• SendTemporaryPassword for Voice OTP request• SendTemporaryPassword for Voice OTP response• SendTemporaryPassword for Voice OTP error codes

SendTemporaryPassword for Voice OTP requestSendTemporaryPassword for Voice OTP input fields provides details about the SendTemporaryPassword for Voice OTPinput fields. Send the request to:


Table 74: SendTemporaryPassword for Voice OTP input fields


TokenId Y String Specifies the phone number thatidentifies the credential to the VIP WebServices. Do not use spaces or dashes.Include the country code (1 for USnumbers). For example:• US: 16505551212• Singapore: 6592123456To specify a phone number, set theattribute type for the TokenId elementto Voice. For example:TokenId type="Voice"

Destination Y for Voice OTP String The phone number to receive thepassword if using Voice OTP only. Donot use spaces or dashes.Include the country code (1 for USnumbers). For example:US: 16505551212Singapore: 6592123456Any appended extension must beginwith lower-case "x", followed by anycombination of the characters * . , # anddigits 0 to 9.Example: 14885554444x,1112• , (comma) Creates a short delay of

approximately 2 seconds• . (period) Creates a longer delay of

approximately 5 seconds• * (star) Used by some phone

systems to access an extension• # (pound or hash). Used by some

phone systems to access anextension.

106




ExpirationDate N dateTime The temporary security code expirationdate (maximum of seven days). If nodate is provided, the default expirationperiod is used to calculate the passwordexpiration.

Account N String Identifies the Symantec Voice Gatewayaccount.See Voice messaging.

Language N Language Specifies the language that is used inthe voice message.See Voice messaging.

See Sample SendTemporaryPassword for Voice OTP SOAP XML request.

Sample SendTemporaryPassword for Voice OTP SOAP XML request



envelope/"



<soapenv:Body>

<SendTemporaryPassword Version="3.1" xmlns="https://schemas.vip.


<TokenId>1234abcd</TokenId>

<Destination type="Voice">16505551212</Destination>


<VoiceDeliveryInfo>


<Account>test_acct</Account>




</SendTemporaryPassword>

</soapenv:Body>

</soapenv:Envelope>

SendTemporaryPassword for Voice OTP responseSendTemporaryPassword for Voice OTP output fields provides details about the SendTemporaryPassword for Voice OTPoutput fields.

Table 75: SendTemporaryPassword for Voice OTP output fields


ReasonCode Y hexBinary If the request to set a temporary security code isunsuccessful, the ReasonCode indicates why the operationfailed.


107


See Sample SendTemporaryPassword for Voice OTP SOAP XML response.

Sample SendTemporaryPassword for Voice OTP SOAP XML response



<Body>

<SendTemporaryPasswordResponse Version="3.1"


<Status>



</Status>

</SendTemporaryPasswordResponse>

</Body>

</Envelope>

SendTemporaryPassword for Voice OTP error codesThis section lists the error codes you may encounter using the SendTemporaryPassword for Voice OTP API.

















Unlocking Voice OTP credentialsCredentials become locked when they exceed the configured number of allowed continuous validation failures. You canunlock users' credentials with the UnlockToken API. You must verify that a user is in possession of their credential beforeyou unlock it. First, verify the user’s identity through some other means, and then request a security code from the user.To check the security code, use the CheckOTP API. If the CheckOTP call succeeds, then make an UnlockToken call.

• Unlock a Voice OTP credential• Getting Token Information for Voice OTP credentials• Sending a temporary security code for Voice OTP

See Checking security codes on locked credentials.

108


Unlock a Voice OTP credentialUse the UnlockToken API to unlock Voice OTP credentials that have become locked. Unlocking a Voice OTP credentialchanges the state of the credential from Locked to Enabled and makes it ready for use (see Credential state changes).

• Unlock for Voice OTP request• Unlock for Voice OTP response• UnlockToken error codes

Unlock for Voice OTP requestUnlockToken for Voice OTP input fields provides details about the UnlockToken for Voice OTP input field. Send therequest to:


Table 76: UnlockToken for Voice OTP input fields



See Sample Unlock for Voice OTP SOAP XML request.

Sample Unlock for Voice OTP SOAP XML request




envelope/"






<SOAP-ENV:Body>


<ns1:TokenId type="Voice">VSMB57361338</ns1:TokenId>

</ns1:UnlockToken>

</SOAP-ENV:Body>


Sample Unlock for Voice OTP responseUnlockToken for SMS OTP output fields provides details about the UnlockToken for Voice OTP output fields.

109





ReasonCode Y hexBinary If an unlock request is unsuccessful, the ReasonCode providesthe reason.

StatusMessage Y String States whether the credential was successfully unlocked.SameInitialState N Boolean States whether the credential changed states.

See Sample Unlock for Voice OTP SOAP XML response.

Sample Unlock for Voice OTP SOAP XML response



<Body>



<Status>



</Status>



</Body>

</Envelope>

UnlockToken error codesThis section lists the error codes you may encounter using the UnlockToken API.















Voice messagingThe VIP Web Service uses Symantec’s Voice Gateway to send voice messages. By default, Symantec’s Voice Gatewayprovides voice messages in English. To send customized messages (for example, messages in another language), anaccount code and a language code are required in the following API operations:

110


• Registering a Voice OTP credential• SendOTP for Voice OTP• Sending a temporary security code for Voice OTP

For information about obtaining an account or about customized messages or languages, contact your Symantecrepresentative.

111


Service-generated OTP credential APIs

The VIP Service includes APIs specific to Service-generated credential types. Use these APIs for all the administrativefunctions that are needed to manage Service-generated OTP credentials for your end users. You must have alreadypurchased Service-generated OTP credentials from Symantec to use these APIs.

VIP can generate a security code and allow your organization to deliver it to a user through a method of your choosing (forexample, by email or your own SMS Gateway). Your application registers a unique device identifier with VIP, which thenvalidates the security code.

All security codes that are returned for Service-generated OTP credentials expire after a set time period. Additionally,Service-generated OTP credentials do not lock. When the Security Code Expiration or Maximum Validation Failures valueis exceeded, the current security code is automatically invalidated. When a new security code is requested, the SecurityCode Expiration and Maximum Validation Failures counters are reset.


• Registering a Service-generated OTP credential• Using the Service-generated OTP credential• Service-generated OTP credential APIs• Additional Service-generated OTP APIs• Getting Token Information for Service-generated OTP credentials

Registering a Service-generated OTP credentialAny device can be used as a credential (see Credential state changes) if it is registered with VIP Web Services. To use adevice as a credential, use the following API calls:

• Register a unique number for the device.See Registering a Service-generated OTP credential.

• ActivateToken for Service-generated OTP to activate the device.See Activating a Service-generated OTP credential,

After being activated, you can manage a Service-generated OTP credential like any other credential.

See Additional Service-generated OTP APIs.

Using the Service-generated OTP credentialAfter the Service-generated OTP credential is registered and activated, use the credential by sending and validatingsecurity codes using the following APIs:

• SendOTP sends a security code to the device.See SendOTP for Service-generated OTP.

• Validate verifies that the security code is sent to the device.See Validate for Service-generated OTP.

112


Service-generated OTP credential APIsService-generated OTP credential APIs lists each Service-generated OTP Credential API and its prerequisites, and cross-references the topics that contain additional information and code samples.

Table 78: Service-generated OTP credential APIs


Service-generated OTP Credential APIsRegister for Service-generatedOTP

Registers a unique alphanumeric ID in VIP. Registering a Service-generatedOTP credential

ActivateToken for Service-generated OTP

Activates a device as a credential. Activating a Service-generatedOTP credential

SendOTP for Service-generatedOTP

Provides a security code for your organization to provide to aregistered user.

Sending a Service-generatedOTP

Validate for Service-generatedOTP

Validates the information about a specific Service-generated OTPcredential’s security code.

Validate for Service-generatedOTP

Additional Service-generated OTP APIsDeactivateToken for Service-generated OTP

Changes the Service-generated OTP credential’s state to inactive. DeactivateToken for Service-generated OTP

EnableToken for Service-generated OTP

Reactivates a Service-generated OTP credential that you havedisabled. If you disable a credential, the user cannot use thecredential until an administrator sets it back to an Enabled state.

EnableToken for Service-generated OTP

DisableToken for Service-generated OTP

Disables a Service-generated OTP credential. DisableToken for Service-generated OTP

GetTokenInformation forService-generated OTP

Gets the information about a Service-generated OTP credential. Getting Token Informationfor Service-generated OTPcredentials

Registering a Service-generated OTP credentialUse the Register API to register a new Service-generated OTP credential (see Credential state changes).

• Register for Service-generated OTP request• Register for Service-generated OTP response• Register for Service-generated OTP error codes

Sample Register for Service-generated OTP requestRegister for Service-generated OTP input fields provides details about the Register for Service-generated OTP inputfields. Send the request to:


113



Table 79: Register for Service-generated OTP input fields


TokenId Y String Specifies the unique alphanumeric ID that identifies thecredential to the VIP Web Services. Do not use spaces ordashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456To specify a unique alphanumeric ID, set the attribute typefor the TokenId element to Service. For example:TokenId type="Service"

Sample Register for Service-generated OTP SOAP XML request



envelope/"



<soapenv:Body>

<Register Id="V0ePCaAoyq" Version="3.1" xmlns="https://schemas.vip.


<TokenId type="Service" >491761212</TokenId>

</Register>

</soapenv:Body>

</soapenv:Envelope>

Register for Service-generated OTP responseRegister for Service-generated OTP output fields provides details about the Register for Service-generated OTP outputfields.

Table 80: Register for Service-generated OTP output fields




See Sample Register for Service-generated OTP SOAP XML response.

Sample Register for Service-generated OTP SOAP XML response



<Body>

<RegisterResponse RequestId="V0ePCaAoyq" Version="3.1" xmlns="https://


<Status>

114




</Status>

<OTP>537886</OTP>

</RegisterResponse>

</Body>

</Envelope>

Register for Service-generated OTP error codesThis section lists the error codes you may encounter using the Register API.













Activating a Service-generated OTP credentialThe ActivateToken for Service-generated OTP API is called when a newly registered Service-generated OTP credentialrequires activation (see Credential state changes).

• ActivateToken for Service-generated OTP request• ActivateToken for Service-generated OTP response• ActivateToken for Service-generated OTP error codes

ActivateToken for Service-generated OTP requestActivateToken for Service-generated OTP input fields provides details about the ActivateToken for Service-generated OTPinput fields. Send the request to:


115



Table 81: ActivateToken for Service-generated OTP input fields




See Sample ActivateToken for Service-generated OTP SOAP XML request.

Sample ActivateToken for Service-generated OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:ActivateToken Id="abcd1cd1234" Version="3.1" xmlns="https://


<TokenId type="Service">491761212</TokenId>

<ns1:OTP1>507638</ns1:OTP1>


</SOAP-ENV:Body>


ActivateToken for Service-generated OTP responseActivateToken for Service-generated OTP output fields lists the ActivateToken for Service-generated OTP output fields.

Table 82: ActivateToken for Service-generated OTP output fields




See Sample ActivateToken for Service-generated OTP SOAP XML response.

116


Sample ActivateToken for Service-generated OTP SOAP XML response

device?xml version="1.0" encoding="UTF-8"?>

deviceEnvelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

deviceBody>

deviceActivateTokenResponse RequestId="abcd1cd1234" Version="3.1"


deviceStatus>

deviceReasonCode>0000device/ReasonCode>

deviceStatusMessage>Successdevice/StatusMessage>

device/Status>

deviceSameInitialState>falsedevice/SameInitialState>

device/ActivateTokenResponse>

device/Body>

</Envelope>

ActivateToken for Service-generated OTP error codesThis section lists the error codes you may encounter using the ActivateToken for Service-generated OTP API.
















4f05: This VIP credential or VIP credential type is not supported for

this account.

Sending a Service-generated OTPUse the SendOTP API to have VIP Web Services prepare a security code for the unique ID. You are responsible forproviding this OTP to your end user. The unique ID must already be registered and activated using the Register andActivateToken API calls.

• SendOTP for Service-generated OTP request• SendOTP for Service-generated OTP response• SendOTP for Service-generated OTP error codes

SendOTP for Service-generated OTP requestSendOTP for Service-generated OTP input fields provides details about the SendOTP for Service-generated OTP inputfield. Send the request to:

117



Table 83: SendOTP for Service-generated OTP input fields



See Sample SendOTP for Service-generated OTP SOAP XML request.

Sample SendOTP for Service-generated OTP SOAP XML request



envelope/"



<soapenv:Body>

<SendOTP Id="abcd1cd1234" Version="3.1" xmlns="https://schemas.vip.



</SendOTP>

</soapenv:Body>

</soapenv:Envelope>

SendOTP for Service-generated OTP responseSendOTP for Service-generated OTP output fields provides details about the SendOTP for Service-generated OTP outputfields.

Table 84: SendOTP for Service-generated OTP output fields




See Sample SendOTP for Service-generated OTP SOAP XML response.

Sample SendOTP for Service-generated OTP SOAP XML response



118



<Body>

<SendOTPResponse RequestId="abcd1cd1234" Version="3.1" xmlns="https://


<Status>



</Status>

<OTP>880548</OTP>

</SendOTPResponse>

</Body>

</Envelope>

SendOTP for Service-generated OTP error codesThis section lists the error codes you may encounter using the SendOTP for Service-generated OTP API.











4e17: The phone number has been deactivated by the carrier; the

number must be registered again




Validating a Service-generated OTPUpon receipt of the security code from the VIP, validate the unique ID number using the Validate for Service-generatedOTP API to authenticate the credential.


• Validate for Service-generated OTP request• Validate for Service-generated OTP response• Validate for Service-generated OTP error codes

Validate for Service-generated OTP requestValidate for Service-generated OTP input fields provides details about the Validate for Service-generated OTP input fields.Send the request to:


119



Table 85: Validate for Service-generated OTP input fields




See Sample Validate for Service-generated OTP SOAP XML request.

Sample Validate for Service-generated OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:Validate Id="abcd1cd1234" Version="3.1" xmlns="https://




</ns1:Validate>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>>

Validate for Service-generated OTP responseValidate for Service-generated OTP output fields provides details about the Validate for Service-generated OTP outputfields.

Table 86: Validate for Service-generated OTP output fields




120







See Sample Validate for Service-generated OTP SOAP XML response.

Sample Validate for Service-generated OTP SOAP XML response



<Body>

<ValidateResponse RequestId="abcd1cd1234" Version="3.1" xmlns="https://


<Status>



</Status>



<FormFactor>SERVICE</FormFactor>




</ValidateResponse>

</Body>

</Envelope>

Validate for Service-generated OTP error codesThis section lists the error codes you may encounter using the Validate for Service-generated OTP API.



121













Additional Service-generated OTP APIsYou can perform the following additional operations for a registered unique ID:

• Deactivate the credential with the DeactivateToken for Service-generated OTP API.See DeactivateToken for Service-generated OTP.

• Enable the credential with the EnableToken for Service-generated OTP API.See EnableToken for Service-generated OTP.

• Disable the credential with the DisableToken for Service-generated OTP API.See DisableToken for Service-generated OTP.

• Retrieve information about the credential with the GetTokenInformation for Service-generated OTP API.See Getting Token Information for Service-generated OTP credentials.

DeactivateToken for Service-generated OTPUse the DeactivateToken for Service-generated OTP API to deactivate a Service-generated OTP credential. If thedeactivation is successful, the credential is deactivated.

• DeactivateToken for Service-generated OTP request• DeactivateToken for Service-generated OTP response• DeactivateToken for Service-generated OTP error codes

See Activating a Service-generated OTP credential.

DeactivateToken for Service-generated OTP requestDeactivateToken for Service-generated OTP input fields provides details about the DeactivateToken for Service-generatedOTP input fields. Send the request to:


122



Table 87: DeactivateToken for Service-generated OTP input fields


TokenId Y String Specifies the unique alphanumeric ID that identifies thecredential to the VIP Web Services. Do not use spaces ordashes.Include the country code (1 for US numbers). For example:• US: 16505551212• Singapore: 6592123456To specify a unique alphanumeric IDr, set the attribute typefor the TokenId element to Service. For example:TokenId type="Service"


See Sample DeactivateToken for Service-generated OTP SOAP XML request.

Sample DeactivateToken for Service-generated OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:DeactivateToken Id="abcd1cd1234" Version="3.1" xmlns="https://


<TokenId type="Service">identifier1</TokenId>

<Reason>Unspecified</Reason>


</SOAP-ENV:Body>


DeactivateToken for Service-generated OTP responseDeactivateToken for Service-generated OTP output fields lists the DeactivateToken for Service-generated OTP outputfields.

Table 88: DeactivateToken for Service-generated OTP output fields




See Sample DeactivateToken for Service-generated OTP SOAP XML response.

123


Sample DeactivateToken for Service-generated OTP SOAP XML response



<Body>

<DeactivateTokenResponse RequestId="abcd1cd1234" Version="3.1" xmlns=


<Status>



</Status>



</Body>

</Envelope>

DeactivateToken for Service-generated OTP error codesThis section lists the error codes you may encounter using the DeactivateToken for Service-generated OTP API.












EnableToken for Service-generated OTPUse the EnableToken for Service-generated OTP API to enable a previously disabled Service-generated OTP credential(see Credential state changes). If the request is successful, the credential is Enabled.

• EnableToken for Service-generated OTP request• EnableToken for Service-generated OTP response• EnableToken for Service-generated OTP error codes

See DisableToken for Service-generated OTP.

EnableToken for Service-generated OTP requestEnableToken for Service-generated OTP input fields provides details about the EnableToken for Service-generated OTPinput fields. Send the request to:


124



Table 89: EnableToken for Service-generated OTP input fields



See Sample EnableToken for Service-generated OTP SOAP XML request.

Sample EnableToken for Service-generated OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:EnableToken Id="abcd1cd1234" Version="3.1" xmlns="https://



</ns1:EnableToken>

</SOAP-ENV:Body>


EnableToken for Service-generated OTP responseEnableToken for Service-generated OTP output fields lists the EnableToken for Service-generated OTP output fields.

Table 90: EnableToken for Service-generated OTP output fields




See Sample EnableToken for Service-generated OTP SOAP XML response.

Sample EnableToken for Service-generated OTP SOAP XML response



125


<Body>

<EnableTokenResponse RequestId="abcd1cd1234" Version="3.1"


<Status>



</Status>

<SameInitialState>true</SameInitialState>


</Body>

</Envelope>

EnableToken for Service-generated OTP error codesThis section lists the error codes you may encounter using the EnableToken for Service-generated OTP API.











DisableToken for Service-generated OTPUse the DisableToken for Service-generated OTP API to disable a Service-generated OTP credential (see Credentialstate changes). If the request is successful, the credential is Disabled.

• DisableToken for Service-generated OTP request• DisableToken for Service-generated OTP response• DisableToken for Service-generated OTP error codes

See EnableToken for Service-generated OTP.

DisableToken for Service-generated OTP requestDisableToken for Service-generated OTP input fields provides details about the DisableToken for Service-generated OTPinput fields. Send the request to:


126



Table 91: DisableToken for Service-generated OTP input fields




See Sample DisableToken for Service-generated OTP SOAP XML request.

Sample DisableToken for Service-generated OTP SOAP XML request



envelope/"






<SOAP-ENV:Body>

<ns1:DisableToken Id="abcd1cd1234" Version="3.1" xmlns="https://



</ns1:DisableToken>

</SOAP-ENV:Body>


DisableToken for Service-generated OTP responseDisableToken for Service-generated OTP output fields lists the DisableToken for Service-generated OTP output fields.

Table 92: DisableToken for Service-generated OTP output fields




See Sample DisableToken for Service-generated OTP SOAP XML response.

Sample DisableToken for Service-generated OTP SOAP XML response


127



<Body>

<DisableTokenResponse RequestId="abcd1cd1234" Version="3.1" xmlns=


<Status>



</Status>



</Body>

</Envelope>

DisableToken for Service-generated OTP error codesThis section lists the error codes you may encounter using the DisableToken for Service-generated OTP API.











Getting Token Information for Service-generated OTP credentialsUse the GetTokenInformation for Service-generated OTP credentials API to get information about a Service-generatedOTP credential (see Credential state changes). If the request is successful, the credential information is displayed.

• GetTokenInformation for Service-generated OTP request• GetTokenInformation for Service-generated OTP response• GetTokenInformation for Service-generated OTP error codes

Getting Token Information for Service-generated OTP credentialsUse the GetTokenInformation for Service-generated OTP credentials API to get information about a Service-generatedOTP credential (see Credential state changes). If the request is successful, the credential information is displayed.

• GetTokenInformation for Service-generated OTP request• GetTokenInformation for Service-generated OTP response• GetTokenInformation for Service-generated OTP error codes

GetTokenInformation for Service-generated OTP requestGetTokenInformation for Service-generated OTP input fields provides details on the GetTokenInformation for Service-generated OTP input fields. Send the request to:


128



Table 93: GetTokenInformation for Service-generated OTP input fields



See Sample GetTokenInformation for Service-generated OTP SOAP XML request.

Sample GetTokenInformation for Service-generated OTP SOAP XML request



envelope/"



<soapenv:Body>

<GetTokenInformation Id="abcd1cd1234" Version="3.1" xmlns="https://



</GetTokenInformation>

</soapenv:Body>

</soapenv:Envelope>

GetTokenInformation for Service-generated OTP responseGetTemporaryPwdExpiration output fields lists the GetTokenInformation for Service-generated OTP output fields.





TokenId Y String Shows a unique string of numeric characters identifying theService-generated credential.


Adapter Y String Shows the credential type: SERVER_OTPTokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,



129






See Sample GetTokenInformation for Service-generated OTP SOAP XML response.

Sample GetTokenInformation for Service-generated OTP SOAP XML response


<Body>

<GetTokenInformationResponse RequestId="V0ePCaAoyq" Version="3.1"


<Status>



</Status>

<TokenInformation>

<TokenId type="Service">IDENTIFIER1</TokenId>


<Adapter>SERVER_OTP</Adapter>




<Owner>true</Owner>

<ReportedReason>Unspecified</ReportedReason>

</TokenInformation>


</Body>

</Envelope>

GetTokenInformation for Service-generated OTP error codesThis section lists the error codes you may encounter using the GetTokenInformation for Service-generated OTP API.











130


Out-of-band Authentication using Voice Calls and SMS

The Out-of-band (OOB) Authentication APIs can streamline confirmation of user transactions by using either voiceprompts or SMS text messages. Out-of-band authentication does not require a credential for user authentication. Instead,it enables users to easily verify their online transactions by using a mobile phone or land line phone.

Your users can take advantage of out-of-band authentication in multiple ways. Although Symantec provides specificexamples of transaction verification through voice calls and text messaging, these examples represent only a subset ofthe parameters available.

To customize out-of-band authentication with additional parameters for your own particular needs, contact your Symantecrepresentative.

• Example user scenarios• Voice call Out-of-band Authentication APIs• SMS out-of-band authentication APIs

Out-of-band Authentication using Voice Calls and SMSThe Out-of-band (OOB) Authentication APIs can streamline confirmation of user transactions by using either voiceprompts or SMS text messages. Out-of-band authentication does not require a credential for user authentication. Instead,it enables users to easily verify their online transactions by using a mobile phone or land line phone.

Your users can take advantage of out-of-band authentication in multiple ways. Although Symantec provides specificexamples of transaction verification through voice calls and text messaging, these examples represent only a subset ofthe parameters available.


• Example user scenarios• Voice call Out-of-band Authentication APIs• SMS out-of-band authentication APIs

Example user scenariosRefer to the following for example scenarios of out-of-band authentication using voice calls and SMS:

• Verifying transactions by entering a response into a phone• Verifying transactions by entering a security code into a website

Verifying transactions by entering a response into a phoneYou can use an automated voice call to prompt a user to enter a specific response into the user’s land line phone ormobile phone. This response provides an interactive layer for the user to verify a particular transaction. The flexibility ofthe voice APIs enables the user to respond in any one of the following ways:

• A user presses the “#” key (or any other designated key).• A user enters an existing Personal Identification Number (PIN) that is already linked to the user’s account.• A user enters a security code from your website. This security code is provided either by your organization or by VIP

services.

Example scenario using voice calls

131


Users can verify completion of online business transactions by using only their mobile phone or land line phone. Exampleof out-of-band authentication using voice calls shows an example of out-of-band authentication using a voice call toconfirm a monetary transaction. In this scenario, ABC Bank has chosen to provide an easy verification process forcustomer transactions by having customers use their current account PIN. Once a customer has initiated an onlineaccount transaction, the bank prompts the customer with a voice call. The bank asks the customer to confirm thetransaction details by entering a PIN directly into the customer’s phone. For example, a bank customer has decidedto initiate a $4,000 wire transfer from his ABC Bank account to an external account. He has immediate access to bothhis phone and his desktop system in his office. After he submitting his transfer using his desktop computer, he receivesa voice call from ABC bank. The voice call asks him to confirm the account number, transfer amount, and monetarycurrency of his transaction. He confirms all the transaction details by entering the PIN for his ABC Bank account into hisphone, using his phone keypad.

Example of out-of-band authentication using voice calls

132


Verifying transactions by entering a security code into a websiteYou can prompt a user with an SMS text message that includes a unique security code to be entered into your website fortransaction verification. This security code is provided either by your organization or by VIP services.

Users can verify completion of online business transactions by entering a security code directly into a website. Thefollowing illustration shows an example of out-of-band authentication using SMS to confirm a monetary transaction. Inthis scenario, XYZ Bank has chosen an SMS verification process for customer transactions. This process requirescustomers to enter use a unique security code, generated by VIP services. Once a customer has initiated an onlineaccount transaction, the bank prompts the customer with an SMS text message. The bank asks the customer to confirmthe transaction details by using the security code that is provided within the message.

Figure 1: Example of out-of-band authentication using SMS

Voice call Out-of-band Authentication APIsThe APIs within this section provide an interactive means for users to verify online transactions through voice prompt anduser confirmation. API calls to the VIP service can include the templates that specify details such as:

• PIN or security code• user’s phone number• currency• amount• account identification


The following APIs are provided for out-of-band authentication:

Table 95: Out-of-band authentication APIs


SubmitTxnVerification Enables a user to verify a transaction. Submit a voice call to promptresponse from user

PollTxnVerification Poll for completion of a voice call to a user. Poll for voice call completionDeliverTxnOTP Delivers a security code by SMS or voice call to a user. Deliver a security code by SMS

or voice callVerifyTxnOTP Verifies a user’s security code. Verify a security code

Submit a voice call to prompt response from user requestSubmitTxnVerification input fields provides details about the SubmitTxnVerification input fields. Send the request to:

https://services-auth.vip.symantec.com/txn/soap

133



Table 96: SubmitTxnVerification input fields

Input Field Required Type Purpose

PhoneNumber Y String Specifies the user’s phone number with country code, butwithout spaces or dashes. As an example, for US:19999999999The phone number must range from 5 to 20 digits. Anyappended extension must begin with lower-case "x",followed by any combination of the characters * . , # anddigits 0 to 9.Example: 19999999999x,1112• , (comma) Creates a short delay of approximately 2




access an extension

TxnOTP N Number Specifies the transaction security code. If the templaterequires a security code but the code is not provided, VIPservices generates and sends a security code in response.

Language N Language One of the ISO 639-1 codes, optionally followed by ahyphen and a two-letter country code. For example, USEnglish is specified as en-us.

VoiceTemplateName Y String Identifies the template that is used for voice calls.A series of NamedParamelements that vary, based onthe VoiceTemplateNameprovided.

N String Varies with the particular VoiceTemplateName used.

See Sample SubmitTxnVerification SOAP XML request.

Sample SOAP XML request<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope




<soapenv:Body>

<SubmitTxnVerification Id="31Ct8H5KOU" Version="3.1"


<PhoneNumber>19999999999</PhoneNumber>

<TxnOTP>468888</TxnOTP>


<VoiceTemplateName>PaymentVerify</VoiceTemplateName>

<NamedParam name="amount">1000</NamedParam>

<NamedParam name="fraction">23</NamedParam>

<NamedParam name="accountEndsWith">12345</NamedParam>

<NamedParam name="currency">USD</NamedParam>

</SubmitTxnVerification>

134


</soapenv:Body>

</soapenv:Envelope>

Submit a voice call to prompt response from user responseSubmitTxnVerification output fields provides details about the SubmitTxnVerification output fields.

Table 97: SubmitTxnVerification output fields

Output Field Required Type Purpose

ReasonCode Y hexBinary Indicates whether a submit request was successful.StatusMessage Y String Describes the ReasonCode.ErrorDetail N String Describes the StatusMessage received from the voice

gateway.See ErrorDetail codes.

TxnId N String A dynamically-generated ID for the transaction. Used insubsequent Poll requests.

See Sample Submit a voice call to prompt response from user SOAP XML response.

Sample Submit a voice call to prompt response from user SOAP XML response<?xml version="1.0" encoding="UTF-8"?>


<Body>

<SubmitTxnVerificationResponse RequestId="31Ct8H5KOU" Version

="2.0"


<Status>


<StatusMessage>Unable to send message to voice gateway for the

given number.</StatusMessage>

<ErrorDetail>Invalid Phone Number (3104)</ErrorDetail>

</Status>

<TxnId>6C4F90CDBE0CD261</TxnId>

</SubmitTxnVerificationResponse>

</Body>

Submit a voice call to prompt response from user error codesYou may possibly encounter the following error codes using the SubmitTxnVerification API.


or format.

4e01: Service internal error.

4e03: Authorization failed.

4e21: Unable to send message to voice gateway for the given number.

135


Poll for voice call completionUse the PollTxnVerification API to poll for completion of a voice call to a user.

Poll for voice call completion requestPollTxnVerification input fields provides details about the PollTxnVerification input fields. Send the request to:


Table 98: PollTxnVerification input fields


TxnId Y String The transaction ID to be polled.

See Sample Poll for voice call completion SOAP XML request.

Sample Poll for voice call completion SOAP XML request


<soapenv:Envelope




<soapenv:Body>

<PollTxnVerification Version="3.1"


<TxnId>6C4F90CDBE0CD261</TxnId>

</PollTxnVerification>

</soapenv:Body>

</soapenv:Envelope>

Poll for voice call completion responsePollTxnVerification output fields provides details about the PollTxnVerification output fields.

Table 99: PollTxnVerification output fields


ReasonCode Y hexBinary Indicates whether a poll request was successful.StatusMessage Y String Describes the ReasonCode.ErrorDetail N String Describes the StatusMessage received from the voice

gateway.See ErrorDetail codes.

TxnOTP N Number This is the OTP the user entered when prompted. Forexample, if the user was prompted to enter the OTP shownin the browser, the OTP that the user entered appears here.

See Sample Poll for voice call completion SOAP XML response.

136



Sample Poll for voice call completion SOAP XML response



<Body>

<PollTxnVerificationResponse Version="3.1"


<Status>


<StatusMessage>Unable to send message to voice gateway for the

given number.</StatusMessage>

<ErrorDetail>Invalid Phone Number (3104)</ErrorDetail>

</Status>

</PollTxnVerificationResponse>

</Body>

</Envelope>

Poll for voice call completion error codesYou may possibly encounter the following error codes using the PollTxnVerification API.


or format.




4e38: Voice call is in progress.

4e3a: Invalid user input.

4e3b: Transaction for the supplied ID has expired.

Submit and Poll for voice call error codesThe following is a list of ErrorDetail descriptions and codes for the SubmitTxnVerification and PollTxnVerification APIs:

Success (0000)

Gateway System Overload (1010)

Gateway System Error (1020)

Invalid Parameters (2140)

Invalid/Inactive TSOID or Invalid/Inactive Application (2142)

XML parsing or validation error (2510)

Invalid Password (2520)

Invalid TEID (2540)

Invalid Country Code (3101)

Invalid Area Code (3102)

Invalid Area Code/ Exchange Combination (3103)

Invalid Phone Number (3104)

Unassigned Phone Number (3110)

Blocked Phone Number (3111)

Network Congestion (3120)

Phone Network Problems (3130)

Special Information Tone (3150)

Line Busy (3210)

FAX Answered (3220)

137


No Answer (3230)

Call Disconnected (3320)

User Telephone Malfunction (3325)

No Affirmation (3340)

Deny Transaction (3350)

Not Expecting Call (3360)

Confirmation Number Failure (3420)

Session in Progress (7000)

SMS out-of-band authentication APIsThe SMS out-of-band authentication APIs provide a non-interactive means for users to verify online transactions throughSMS delivery of a security code. API calls to the VIP service specify the security code and the user’s phone number. Tocustomize an out-of-band authentication SMS text message, use the Message field in the DeliverTxnOTP request asdescribed in DeliverTxnOTP input fields.

When a user receives an SMS message to enter the security code that is generated from either your organization or VIPservices, the user enters the security code within your website to confirm the transaction.

The following APIs are provided for out-of-band authentication using SMS text messages (or voice calls):

• Deliver a security code by SMS or voice call (DeliverTxnOTP)• Verify a security code (VerifyTxnOTP)

Deliver a security code by SMS or voice callUse the DeliverTxnOTP API to deliver a security code by SMS or voice call to a user.

• Deliver a security code by SMS or voice call request• Deliver a security code by SMS or voice call response• Deliver a security code by SMS or voice call error codes

Deliver a security code by SMS or voice call requestDeliverTxnOTP input fields provides details about the DeliverTxnOTP input fields. Send the request to:


138



Table 100: DeliverTxnOTP input fields


TxnOTP N String Security code that is delivered to a user through SMS. If notspecified, VIP Services dynamically generates a securitycode and delivers it through SMS.

Destination Y String The destination phone number to receive the security code.To specify an SMS or voice call message, set the attributetype accordingly. For example, type="SMS" or type="Voice"If the type is Voice, the phone number must range from 5 to20 digits. Any appended extension must begin with lower-case "x", followed by any combination of the characters * . ,# and digits 0 to 9.Example: 19999999999x,1112• , (comma) Creates a short delay of approximately 2




access an extension

See Sample Deliver a security code by SMS or voice call SOAP XML request .

Sample Deliver a security code by SMS or voice call SOAP XML request


<soapenv:Envelope




<soapenv:Body>

<DeliverTxnOTP Version="3.1" Id="1234abcd"



<Destination type="SMS">19999999999</Destination>

</DeliverTxnOTP>

</soapenv:Body>

</soapenv:Envelope>

Deliver a security code by SMS or voice call responseDeliverTxnOTP output fields provides details about the DeliverTxnOTP output fields.

Table 101: DeliverTxnOTP output fields


ReasonCode Y hexBinary Indicates whether a deliver request was successful.StatusMessage Y String Describes the ReasonCode.TxnId Y String A dynamically-generated ID for the transaction.

139


See Sample Deliver a security code by SMS or voice call SOAP XML response.

Sample Deliver a security code by SMS or voice call SOAP XML response



<Body>

<DeliverTxnOTPResponse RequestId="1234abcd" Version="3.1"


<Status>



</Status>

<TxnId>892B1D4C65D1CA57</TxnId>

</DeliverTxnOTPResponse>

</Body>

</Envelope>

Deliver a security code by SMS or voice call error codesYou may possibly encounter the following error codes using the DeliverTxnOTP API.


or format.



4e1a: Unable to send SMS to given number through gateway.


Verify a security codeUse the VerifyTxnOTP API to verify a user’s security code.

• Verify security code request• Verify security code response• Verify security code error codes

Verify security code requestVerifyTxnOTP input fields provides details about the VerifyTxnOTP input fields. Send the request to:


Table 102: VerifyTxnOTP input fields


TxnId Y String Transaction ID returned from the DeliverTxnOTP API.TxnOTP Y String Specifies the transaction security code to be validated. If

the security code is not provided, VIP services generatesand sends a security code in response.

See Sample Verify security code SOAP XML request.

140



Sample Verify security code SOAP XML request


<soapenv:Envelope




<soapenv:Body>

<VerifyTxnOTP Version="3.1"


<TxnId>601B82D6E9AA8128</TxnId>


</VerifyTxnOTP>

</soapenv:Body>

</soapenv:Envelope>

Verify security code responseVerifyTxnOTP output fields provides details about the VerifyTxnOTP output fields.

Table 103: VerifyTxnOTP output fields


ReasonCode Y hexBinary Indicates whether a verify request was successful.StatusMessage Y String Describes the ReasonCode.

See Sample Verify security code SOAP XML response.

Sample Verify security code SOAP XML response



<Body>

<VerifyTxnOTPResponse Version="3.1"


<Status>



</Status>

</VerifyTxnOTPResponse>

</Body>

</Envelope>

Verify security code error codesYou may possibly encounter the following error codes using the VerifyTxnOTP API.


or format.



4e3a: Invalid user input.

141


4e3f: Security code expired.

142


VIP Web Services error codes

VIP web services error codes lists the VIP Web Services error codes.

Table 104: VIP web services error codes

Error Code Cause Solution

4804 Invalid security code (OTP). The security codelength you provided is more than six characters, or itcontains non-numeric characters.

Check the security code, and try the operation again.The security code must be exactly six numericcharacters.

4837 Input data is not as expected. The data that was entered is the wrong type. Checkthe data and retry the operation.

4840 The VIP service does not support this operation forthis token type.

Use the appropriate credential type for thatoperation.See VIP Service credential management APIs.

4845 The request parameters you supplied contain anunexpected value or format.

If the request parameter is a 16-byte challengephrase, be sure that it is in hex format.If the request parameter is a security code, be surethat it is a six-digit numeric value.Check the request parameters for the operation youare trying to perform.See VIP Service credential management APIs.

4879 The VIP service is temporarily unavailable. Try the operation again later.4918 Invalid security code. The security code length you

provided is less than six characters.Check the security code, and try the operation again.The security code must be exactly six numericcharacters.

4923 The security code you provided is within the Syncwindow, but outside the Look Ahead Window. Thisoperation requires a second consecutive securitycode.

Provide a second consecutive security code.

4940 Database error. An unexpected database error occurred at the WebService. Contact Customer Support for assistance.

4946 Unable to decrypt OTP secret. The security code secret cannot be decrypted.4951 Invalid Request. You must set a temporary security

code for this credential before you can change thetemporary security code expiration date.

See Setting and managing temporary securitycodes.

4952 The temporary security code does not contain thecorrect number of numeric characters.


4953 Expiration must be later than the current time, andno more than seven days from now.


4990 Bad credential state or credential is expired. See Credential states.If credential is expired, the user must obtain areplacement credential.

4991 The jurisdiction hash for this credential is empty ordoes not match your account.

Contact Customer Support.

143



4992 This operation is not allowed on an enabledcredential.

The operation you attempted is not allowedon a credential in the Enabled state. Use thegetTokenInformation API to find out the state of eachcredential.See Getting information about a credential.See Credential states.

4993 This operation is not allowed on a disabledcredential.

The operation you attempted is not allowedon a credential in the disabled state. Use thegetTokenInformation API to find out the state of eachcredential.See Getting information about a credential.

4994 This operation is not allowed on a locked credential. The operation you attempted is not allowedon a credential in the locked state. Use thegetTokenInformation API to find out the state of eachcredential.See Getting information about a credential.

4995 This operation is not allowed on a new credential. The operation you attempted is not allowedon a credential in the new state. Use thegetTokenInformation API to find out the state of eachcredential.See Getting information about a credential.

4996 This operation is not allowed on an inactivecredential.

The operation you attempted is not allowedon a credential in the inactive state. Use thegetTokenInformation API to find out the state of eachcredential.See Getting information about a credential.

4997 Validation failed.This error code is used for the ValidateMultiple APIonly.See Validating multiple credentials.

Use the getTokenInformation API to find out thecredential state.See the appropriate topic:• Getting information about a credential• To enable a disabled credential, see “Enabling

Credentials” on page 25.• To enable a locked credential, see “Unlocking

Credentials” on page 22.• To enable a new credential or inactive credential,

see “Activating/Deactivating Credentials” onpage 11.

If the credential is already enabled, the security codemay be invalid. Try the operation again with a validsecurity code.

49b5 Failed with an invalid security code. The Web Service cannot validate the credentialusing the security code you provided.

4bf1 Unsupported credential type. The Web Service does not currently support thecredential type you supplied.See Getting information about a credential.

4b52 You have already linked to this token credential Linking to this credential is not required. Howeverif you do, make sure that it is unlinked before youperform this operation.

4b53 You have not yet linked to this token credential Be sure that the link is created before you performthis operation.

144



4e00 Malformed request. The request that the Web Service received ismalformed.See Malformed request error details.

4e01 Service internal error. An unexpected error occurred at the Web Service.Contact Customer Support.

4e02 Authentication failed. The authentication request failed, possibly becauseof an incorrect VIP certificate type.See Obtaining your VIP certificate.

4e03 Authorization failed. The authorization failed.See Authorization Failed error details.

4e04 Unsupported VIP Service protocol version. Your XML request or SOAP request contains anunsupported protocol version of VIP Web Services.

4e07 The supplied activation code is invalid. Obtain a valid activation code.4e08 The supplied activation code profile is invalid. Obtain a valid activation code profile.4e0a The orders for this credential type have already been

fulfilled or have expired.Use a different order profile ID.

4e0b VIP certificate revoked. The VIP certificate you are using has been revoked.See Obtaining your VIP certificate .

4e10 This URL does not support this operation. The URL for this API is incorrect. To find the correctURL.See VIP Service credential management APIs.

4e11 Credential ID has been revoked. The credential is revoked. Contact CustomerSupport.

4e12 Invalid Request. No temporary security code isassociated with this credential.

You attempted a temporary security code operationon a credential with no associated temporarysecurity code.See Setting and managing temporary securitycodes.

4e14 The VIP Service does not support this request. The Web Service does not support this request type.See VIP Service credential management APIs.

4e15 Site does not support this operation. To offer high availability service, the Web Servicesometimes switches between its primary site andits secondary site. The Web Service secondary sitesupports validation operations only, so this errorcondition occurs when the secondary site receives aprovisioning request or management request.See About best practices for high availability andoptimal performance.

4e16 The phone number has not been registered for thisaccount.

Contact your Web Service provider to register thephone number.

4e17 The phone number has been deactivated by thecarrier; the number needs to be registered.

The phone number entered is not recognized bythe system. Contact your Web Service provider andregister the phone number.

4e1a Unable to send SMS message to the phone numberthrough the gateway.

Check the phone number and try again.

4e1b The phone number has already been activated. Check the phone number and try again.4e1c Missing message template for the given tag and

request type.Supply a message template that applies to the tagand request type.

145



4e1d A security code is required to activate a new phonenumber.

The registered phone number is in the new state andneeds a new security code to register with the WebService.

4e21 Unable to send message to voice gateway for thegiven number.

Check if the given phone number is correct. If thephone number is correct, check the error detail formore information.

4e22 The type value of Destination element is notsupported for this API.

Consult the VIP Services WSDL for the correct typevalue of Destination element.

4e38 Voice call is in progress. Use the PollTxnVerification API to poll for thestatus of the call until the call is over.

4e3a Invalid user input. When the user is prompted to enter a response(such as the "#" key or a transaction security codeshown on the screen), the user did not enter theexpected response. This may be due to human erroror because the user wants to deny the transaction.

4e3b Transaction for the supplied ID has expired. A transaction ID is valid while the call is ongoingand for a short period of time after the call is over.If PollTxnVerification is called after a longperiod of time for a voice call that is already over,you will get this response. Check the error detail ofthe response for more information.

4e3f Security code expired. The security code has expired. Request a newsecurity code.

4bf1 This credential type does not support this operation. You may not be able to perform some operationswith certain credential types.For example, you cannot set a temporary passwordusing an OCRA signing credential.

4f05 The policy for this account does not support this VIPcredential or VIP credential type.

Verify the user’s supported credentials within the VIPManager policy.

Error detailsMalformed request error details shows error details for the 4e00 (malformed request) errors.

Authorization Failed error details shows error details for the 4e03 (authorization failed) errors.

Malformed request error details

Table 105: Error details for 4e00 (Malformed request)

Error Detail Solution

Invalid URL or content type (XML or SOAP) Check the URL and sample code for the operation you are trying to perform.See VIP Service credential management APIs.

Invalid parameters in request Check the request parameters for the operation you are trying to perform.See VIP Service credential management APIs.

Request size too large You have exceeded the maximum number of characters allowed in the request.Content of the SOAP Body element not valid Check the SOAP code for the operation you are trying to perform.

See VIP Service credential management APIs.SOAP request elements or namespace is not valid. As stated.

146


Error Detail Solution

XML request message is not valid. As stated.XML request elements or namespace is not valid. As stated.Missing required parameter (credential_model) in therequest

You must supply the credential model in this request. You can find the credentialmodel using the getTokenInformation API.See Getting information about a credential.

A required parameter (the security code) is missing. You must supply a security code for this operation. Check the requestparameters for the operation you are trying to perform.See VIP Service credential management APIs.

A required parameter (the version) is missing. You must include the API version number in the request. In the followingexample, the version number is “3.1”:<ns1:ActivateToken Version="3.1" Id="EHCF6443">

A required parameter (the nonce) is missing. You must include the nonce in this request. The nonce is a unique identifier youinclude for logging and audit purposes. In the following example, the nonce is“EHCF6443”:<ns1:ActivateToken Version="3.1" Id="EHCF6443">

The parameters in this request are invalid ormissing.

Check the request parameters for the operation you are trying to perform.See VIP Service credential management APIs.

XML request element value does not conform todata type.

Check the request parameters for the operation you are trying to perform.See VIP Service credential management APIs.

INVALID_REQUEST_TOKEN_TYPE Request is not allowed for the specified credential type.INVALID_PHONE_NUMBER The phone number should be numeric and between 5 and 20 digits.INVALID_TEMPLATE_VALUE REGISTER, SERVICE and TEMP_PASSWORD template must have _OTP_ as

a part of the message.INVALID_MESSAGE_LENGTH Message length should be greater than 0 and not more than 160 characters.MISSING_SMS_FROM Missing SMS From information.MISSING_GATEWAY_INFO Gateway account information is required.MISSING_GATEWAY_PASSWORD Gateway password is required.INVALID_GATEWAY_INFO Gateway account information is invalid.

Authorization Failed error details

Table 106: Error details for 4e03 (Authorization Failed)

Onscreen Error Message Solution

Account not authorized to perform requestedoperation

Your account is not authorized to perform this operation, or your account did notissue this credential. Retry this operation with the correct account, or try anotheroperation.

Account not found You are using the wrong type of VIP Registration Authority (RA) certificate, orthe account on your VIPRA certificate is not in the Web Services database.Retry the operation using the correct VIPRA certificate or obtain a new one.See Obtaining your VIP certificate.

This is not a VIP issuer. You must have a VIP issuer account to perform this operation. Retry thisoperation with the correct account, or try another operation.

Credential does not belong to a VIP issuer. Thisoperation is only allowed for VIP credentials.

Try the operation again using a valid VIP credential.

147


Onscreen Error Message Solution

Credential ID not found This credential ID is not in the VIP service database. Try again using a knowncredential ID.

Your account did not issue this credential. You are not authorized to perform this operation for this credential because youraccount did not issue the credential. Only the account that issued this credentialis authorized to perform this operation.

You must be a VIP customer to perform thisoperation.

You are not authorized to perform this operation.See VIP Service credential management APIs.

148


Best practices for high availability and optimal performance

You need to follow the best practices to ensure high availability and optimal performance with the VIP Service.

• For every request that is sent to the VIP Services, you need to use a unique request ID. This information is helpfulduring troubleshooting to correlate the logs. Symantec recommended that you use a prefix to identify the subsystem,followed by a random string.For example, you can use "2FAUTHXXXXXXX" to identify all the requests that originated from your two-factorauthentication system.

• Symantec recommends that you disable DNS caching for customers to benefit from the VIP Services' active-active High Availability feature. If the customer application is coded in Java, be sure to read the following:– Most Java JVMs cache DNS entries by default and ignore the TTL that is specified in the DNS protocol. If your

application is Java-based, you need to disable this behavior by setting the networkaddress.cache.ttl andnetworkaddress.cache.negative.ttl Java security properties to 0.You can read more about this setting in the JDK documentation at http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html.

• Enable HTTP 1.1 Keep-aliveSymantec highly recommends that you enable HTTP Keep-alive to save the setup cost for every subsequent requestafter you have established a connection.

• Use connection poolsYou can use this option to avoid creating new connections. Because connection pool parameters vary, you need torefer to the Web Services library documentation on how to enable and tune connection pools.

• Read and write timeoutsMake sure that your client has both options set to reasonable values. Instead of hanging, build clients with timeoutsand retry mechanisms. It helps clients to fail fast and retry, thus leading to faster recovery.

• Do not rely on SSL session resumption.Due to the load balancing algorithms we use, SSL session resumption is not supported in VIP Services.

• GetServerTime APIFor monitoring purposes, you need to use GetServerTime API. It ensures that you have connectivity from the clientside. It also provides an estimate of the lowest response time that you can expect from the client side becauseGetServerTime is a "lightweight" API.

• Bulk updates during off-peak hoursIf you run any bulk updates, such as disabling all the credentials of users who are inactive, you must run the bulkupdates during off-peak hours. Typically, these hours should be scheduled during weekends or between 12:00 AMPST to 3:00 AM PST.

149

http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html

http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html


SMS short codes and long codes in VIP

VIP uses its own short code and account information for the SMS API.

Network providers can use their own short code or long code instead of the default codes that are provided by VIP to sendSMS requests. If they choose to use their own code, the code must be registered with the SMS gateway to be used withVIP. If the modified code is used as a default, but is not registered with the SMS gateway, the message is not sent andfeedback is not provided.

The code is customized in the SMSFrom field of the account. Only one value can be customized (short code or longcode). The customized value is used as the default if an override is not included in the SMS message.

The network provider can also override the default short code or message on a per request basis by sending them as partof the SMS request. This override is used only for that single request and is not saved.

Most SMS requests are sent through the VIP account in the SMS gateway. The only exception is aSendTemporaryPassword request, which requires a user name and password for the SMS gateway account.

If the default codes are not customized or sent as an override code, VIP uses the default short code. VIP usesGOVIP(46847) as the default short code.

When sending an SMS message internationally without the long code that is configured or registered with the SMSGateway for the account, the VIP long code is used as an override for that part of the message or the account defaultSMSFrom number. The VIP long code is sent to you through documentation and is not set as a default with the WebService.

Sending an SMS messageNote the following when sending an SMS message to a specific SMS code addressable region:

• The VIP short code can be modified to send an SMS request within the U.S. by customizing the SMSFrom short code.• To send a message within the U.S., a short code is not required. The VIP default short code is detected automatically.

European character support for international phone numbersThe SMS gateway supports ASCII and Global System for Mobile (GSM) characters to send SMS messages. The GSMcharacter set supports most European characters.

See GSM default character set.

To send a message in the European character-set to a European phone requires the following:

• That the European characters are supported in the GSM character set• That the UTF-8 format is used as part of the request

Characters that are not supported by the GSM character-set are sent as question marks (?). VIP does not check the SMSmessage against the supported character set, and feedback is not provided for any unsupported characters.

GSM default character set

150


151


Copyright Statement

Broadcom, the pulse logo, Connecting everything, and Symantec are among the trademarks of Broadcom.

Copyright ©2020 Broadcom. All Rights Reserved.

The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. For more information, please visitwww.broadcom.com.

Broadcom reserves the right to make changes without further notice to any products or data herein to improve reliability,function, or design. Information furnished by Broadcom is believed to be accurate and reliable. However, Broadcom doesnot assume any liability arising out of the application or use of this information, nor the application or use of any product orcircuit described herein, neither does it convey any license under its patent rights nor the rights of others.

152

http://www.broadcom.com

Symantec VIP Web Services Developer's Guide

Documents

Transcript of Symantec VIP Web Services Developer's Guide