Upload
others
View
8
Download
0
Embed Size (px)
Citation preview
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
For a credential management API to work successfully, a credential must be in the correct state for that API.
See Credential states.
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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 Credential states.
See Sample ActivateToken SOAP XML response.
Sample ActivateToken SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<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
Symantec VIP Web Services Developer's Guide
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.
See Credential states.
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 5: DeactivateToken input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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
<?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:DeactivateToken Version="3.1" Id="JFGJ7808">
<ns1:TokenId>VSMB86856915</ns1:TokenId>
<ns1:Reason>Lost</ns1:Reason>
22
Symantec VIP Web Services Developer's Guide
</ns1:DeactivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Deactivation responseDeactivateToken output fields provides details about the DeactivateToken output fields.
Table 6: DeactivateToken output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DeactivateTokenResponse RequestId="JFGJ7808" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<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,
See VIP Web Services error codes.
4990: Bad Token State
4995: Operation not allowed on a new token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
23
Symantec VIP Web Services Developer's Guide
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
Input Field Required? Type Purpose
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
<?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#"
24
Symantec VIP Web Services Developer's Guide
xmlns:ns1="https://schemas.vip.symantec.com/2006/08/vipservice">
<SOAP-ENV:Body>
<ns1:Validate Version="3.1" Id="CDCE1500">
<ns1:TokenId>VSMB51547642</ns1:TokenId>
<ns1:OTP>893818</ns1:OTP>
</ns1:Validate>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Validation responseValidate output fields lists the Validate output fields.
Table 8: Validate output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ValidateResponse RequestId="CDCE1500" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
25
Symantec VIP Web Services Developer's Guide
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4879: The service is temporarily unavailable
4990: Bad Token State
4993: Operation not allowed on a disabled token
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4997: Validation failed
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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:
https://services-auth.vip.symantec.com/val/soap
26
Symantec VIP Web Services Developer's Guide
Table 9: ValidateMultiple input fields
Input Field Required? Type Purpose
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<"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://schemas.vip.symantec.com/
2006/08/vipservice" Version="3.1" Id="1234abcd">
<TokenIds>VSMB45948855</TokenIds>
<TokenIds>VSMB86692863</TokenIds>
<TokenIds>VSMB21518952</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
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
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 codeis generated in hardware or software.
See Sample ValidateMultiple SOAP XML response.
Sample ValidateMultiple SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<ValidateMultipleResponse RequestId="1234abcd" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SuccessfulTokenId>VSMB45948855</SuccessfulTokenId>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</ValidateMultipleResponse>
ValidateMultiple error codesThis section lists the error codes you may encounter using the ValidateMultiple API.
See VIP Web Services error codes.
4879: The service is temporarily unavailable
4990: Bad Token State
4993: Operation not allowed on a disabled token
4994: Operation not allowed on a locked token
28
Symantec VIP Web Services Developer's Guide
4995: Operation not allowed on a new token
4996: Operation not allowed on a inactive token
4997: Validation failed.
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
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:
https://services-auth.vip.symantec.com/val/soap
Table 11: ValidateCR input fields
Input Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Input Field Required? Type Purpose
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
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
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 codeis generated in hardware or software.
See Sample ValidateCR SOAP XML response.
Sample ValidateCR SOAP XML response
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ValidateCRResponse RequestId="abcd123" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SuccessfulTokenId>VSOC99000019</SuccessfulTokenId>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</ValidateCRResponse>
</Body>
</Envelope>
ValidationCR error codesThis section lists the error codes you may encounter using the ValidateCR API.
See VIP Web Services error codes.
4879: The service is temporarily unavailable
31
Symantec VIP Web Services Developer's Guide
4990: Bad Token State
4993: Operation not allowed on a disabled token
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on a inactive token
4997: Validation failed
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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:
https://services-auth.vip.symantec.com/val/soap
Table 13: Synchronize input fields
Input Field Required? Type Purpose
TokenIds Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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
Symantec VIP Web Services Developer's Guide
Input Field Required? Type Purpose
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" ?>
<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:Synchronize Version="3.1" Id="GJBC8741">
<ns1:TokenId>VSMB26155954</ns1:TokenId>
<ns1:OTP1>061792</ns1:OTP1>
<ns1:OTP2>165689</ns1:OTP2>
</ns1:Synchronize>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Synchronization responseSynchronization output fields lists the Synchronize output fields.
Table 14: Synchronization output fields
Output Field Required? Type Purpose
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" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SynchronizeResponse RequestId="GJBC8741" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
33
Symantec VIP Web Services Developer's Guide
</Status>
</SynchronizeResponse>
</Body>
</Envelope>
Synchronize error codesThis section lists the error codes you may encounter using the Synchronize API.
See VIP Web Services error codes.
4845: The request parameters you supplied contain an unexpected value or
format.
4879: The service is temporarily unavailable
4993: Operation not allowed on a disabled token
4994: Operation not allowed on a locked token
4996: Operation not allowed on a inactive 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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
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:
https://services-auth.vip.symantec.com/mgmt/soap
34
Symantec VIP Web Services Developer's Guide
Table 15: UnlockToken input fields
Input Field Required? Type Purpose
TokenIds Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
See Sample UnlockToken SOAP XML request.
Sample UnlockToken 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:UnlockToken Version="3.1" Id="BGFA5527">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
</ns1:UnlockToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Unlock responseUnlockToken output fields provides details about the UnlockToken output fields.
Table 16: UnlockToken output fields
Output Field Required? Type Purpose
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" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<UnlockTokenResponse RequestId="BGFA5527" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
35
Symantec VIP Web Services Developer's Guide
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</UnlockTokenResponse>
</Body>
</Envelope>
UnlockToken error codesThis section lists the error codes you may encounter using the UnlockToken API.
See VIP Web Services error codes.
4990: Bad Token State
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
• 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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 17: DisableToken input fields
Input Field Required? Type Purpose
TokenIds Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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
<?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:DisableToken Version="3.1" Id="JEJI2285">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
<ns1:Reason>Lost</ns1:Reason>
</ns1:DisableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Disable responseDisable output fields provides details about the DisableToken output fields.
37
Symantec VIP Web Services Developer's Guide
Table 18: Disable output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DisableTokenResponse RequestId="JEJI2285" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DisableTokenResponse>
</Body>
</Envelope>
DisableToken error codesThis section lists the error codes you may encounter using the DisableToken API.
See VIP Web Services error codes.
4990: Bad Token State
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
Enabling credentialsCredentials cannot be used, tested, or synchronized unless they are Enabled. Use the EnableToken API to enablecredentials that an issuer has disabled.
38
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 19: Enable input fields
Input Field Required? Type Purpose
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" ?>
<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:EnableToken Version="3.1" Id="IAHD7313">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
</ns1:EnableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Enable requestEnable input fields provides details about the EnableToken input field. Send the request to:
https://services-auth.vip.symantec.com/mgmt/soap
Table 20: Enable input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to the VIPService Web Services.
39
Symantec VIP Web Services Developer's Guide
See Sample EnableToken SOAP XML request.
Sample EnableToken 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:EnableToken Version="3.1" Id="IAHD7313">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
</ns1:EnableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
EnableToken error codesThis section lists the error codes you may encounter using the EnableToken API.
See VIP Web Services error codes.
4990: Bad Token State
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
• 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:
https://services-auth.vip.symantec.com/mgmt/soap
41
Symantec VIP Web Services Developer's Guide
Table 21: SetTemporaryPassword input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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
<?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:SetTemporaryPassword Version="3.1" Id="GJGB2050">
<ns1:TokenId>VSMB39392725</ns1:TokenId>
<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>
</SOAP-ENV:Envelope>
SetTemporaryPassword responseSetTemporaryPassword output fields provides details about the SetTemporaryPassword output fields.
Table 22: SetTemporaryPassword output fields
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Sample SetTemporaryPassword SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SetTemporaryPasswordResponse RequestId="IGEH4431" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</SetTemporaryPasswordResponse>
</Body>
</Envelope>
SetTemporaryPassword error codesThis section lists error codes you may encounter using the SetTemporaryPassword API.
See VIP Web Services error codes.
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
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
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
Symantec VIP Web Services Developer's Guide
• GenerateTemporaryPassword request• GenerateTemporaryPassword response• GenerateTemporaryPassword error codes
GenerateTemporaryPassword requestGenerateTemporaryPassword input fields provides details about the GenerateTemporaryPassword input fields. Send therequest to:
https://services-auth.vip.symantec.com/mgmt/soap
Table 23: GenerateTemporaryPassword input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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:xsd="http://www.w3.org/2001/XMLSchema"
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
Symantec VIP Web Services Developer's Guide
Table 24: GenerateTemporaryPassword output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<GenerateTemporaryPasswordResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TemporaryPassword>972947</TemporaryPassword>
</GenerateTemporaryPasswordResponse>
</Body>
</Envelope>
GenerateTemporaryPassword error codesThis section lists error codes you may encounter using the GenerateTemporaryPassword API.
See VIP Web Services error codes.
4953: Expiration date must be later than the current time, and no
more than 7 days from now
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
45
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 25: SetTemporaryPwdExpiration input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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
<?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:SetTemporaryPwdExpiration Version="3.1" Id="CCJH0357">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
<ns1:ExpirationDate>2007-01-30T18:12:45-08:00</ns1:ExpirationDate>
</ns1:SetTemporaryPwdExpiration>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SetTemporaryPwdExpiration responseSetTemporaryPwdExpiration output fields provides details about the SetTemporaryPwdExpiration output fields.
46
Symantec VIP Web Services Developer's Guide
Table 26: SetTemporaryPwdExpiration output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SetTemporaryPwdExpirationResponse RequestId="CCJH0357" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</SetTemporaryPwdExpirationResponse>
</Body>
</Envelope>
SetTemporaryPwdExpiration error codesThis section lists the error codes you may encounter using the SetTemporaryPwdExpiration API.
See VIP Web Services error codes.
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
4990: Bad Token State
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
47
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 27: SetTemporaryPwdExpiration input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
See Sample GetTemporaryPwdExpiration SOAP XML request.
Sample GetTemporaryPwdExpiration 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:GetTemporaryPwdExpiration Version="3.1" Id="IGIC1317">
<ns1:TokenId>VSMB12351597</ns1:TokenId>
</ns1:GetTemporaryPwdExpiration>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
GetTemporaryPwdExpiration responseGetTemporaryPwdExpiration output fields provides details about the GetTemporaryPwdExpiration output fields.
48
Symantec VIP Web Services Developer's Guide
Table 28: GetTemporaryPwdExpiration output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<GetTemporaryPwdExpirationResponse RequestId="IGIC1317" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4990: Bad Token State
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4e12: Invalid Request. There is no temporary password associated with
this token
4bf1: This credential type does not support this operation
49
Symantec VIP Web Services Developer's Guide
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.
See Credential states.
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:
https://services-auth.vip.symantec.com/mgmt/soap
50
Symantec VIP Web Services Developer's Guide
Table 29: CheckOTP input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
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: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:CheckOTP Version="3.1" Id="BJFF6556">
<ns1:TokenId>VSMB57361338</ns1:TokenId>
<ns1:OTP1>189440</ns1:OTP1>
<ns1:OTP2>670438</ns1:OTP2>
</ns1:CheckOTP>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Response for checking a security code on a locked credentialCheckOTP output fields provides details about the CheckOTP output fields.
Table 30: CheckOTP output fields
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
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 codeis generated in hardware or software.
See Sample CheckOTP SOAP XML response.
Sample CheckOTP SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<CheckOTPResponse RequestId="BJFF6556" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</CheckOTPResponse>
</Body>
</Envelope>
CheckOTP error codesThis section lists the error codes you may encounter using the CheckOTP API.
See VIP Web Services error codes.
52
Symantec VIP Web Services Developer's Guide
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
4995: Operation not allowed on new token
4996: Operation not allowed on an inactive token
49f2: Token ID not found
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 31: getTokenInformation input fields
Input Field Required? Type Purpose
TokenId Y String The token ID (credential ID) identifies the credential to theVIP Service Web Services.
53
Symantec VIP Web Services Developer's Guide
See Sample getTokenInformation SOAP XML request.
Sample getTokenInformation 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:getTokenInformation Version="3.1" Id="ACGC0670">
<ns1:TokenId>VSMB21481289</ns1:TokenId>
</ns1:getTokenInformation>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
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.
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 codeis generated in hardware or software.
See Sample getTokenInformation SOAP XML response.
Sample getTokenInformation SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<getTokenInformationResponse RequestId="FECG8273" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
55
Symantec VIP Web Services Developer's Guide
<TokenInformation>
<TokenId>VSMB21481289</TokenId>
<TokenKind>SOFTWARE</TokenKind>
<Adapter>OATH_EVENT_BASIC</Adapter>
<TokenStatus>ENABLED</TokenStatus>
<ExpirationDate>2011-08-11T13:48:03.000-07:00</ExpirationDate>
<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>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</getTokenInformationResponse>
</Body>
</Envelope>
getTokenInformation error codesThis section lists the error codes you may encounter using the getTokenInformation API.
See VIP Web Services error codes.
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4bf1: This credential type does not support this operation
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
Symantec VIP Web Services Developer's Guide
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.
<?xml version="2.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<SetTemporaryPwdExpiration
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://schemas.vip.symantec.com/2006/08/
vipservice" Version="3.1" Id="1234abcd">
<AuthorizerAccountId>72480532</AuthorizerAccountId>
<TokenId>VSME25439494</TokenId>
<ExpirationDate>2010-06-07T18:44:27.222-08:00</ExpirationDate>
</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.
<?xml version="2.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SetTemporaryPwdExpirationResponse RequestId="1234abcd" Version=
"3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</SetTemporaryPwdExpirationResponse>
</Body>
</Envelope>
57
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
API Name Description See
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ValidateResponse RequestId="DGGE4550" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<NetworkAlert>true</NetworkAlert>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</ValidateResponse>
</Body>
</Envelope>
59
Symantec VIP Web Services Developer's Guide
Get Token Information with Network IntelligenceUse the getTokenInformation API to retrieve detailed information for a registered credential.
Sample getTokenInformation response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<getTokenInformationResponse RequestId="CCFD6815" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenInformation>
<TokenId type="SMS">3424567</TokenId>
<TokenKind>SOFTWARE</TokenKind>
<Adapter>SMS_OTP</Adapter>
<TokenStatus>DISABLED</TokenStatus>
<ExpirationDate>2011-01-08T17:31:53.000-08:00</ExpirationDate>
<LastUpdate>2008-01-09T17:58:58.000-08:00</LastUpdate>
<Owner>true</Owner>
<ReportedReason>Stolen</ReportedReason>
</TokenInformation>
<TokenCategoryDetails>
<CategoryId>69</CategoryId>
<FormFactor>MOBILE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SOFTWARE</OtpGeneratedBy>
</TokenCategoryDetails>
</getTokenInformationResponse>
</Body>
</Envelope>
60
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
API Name Description See
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
Symantec VIP Web Services Developer's Guide
Table 36: Register for SMS OTP input fields
Input Field Required? Type Purpose
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
<?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: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:SMSDeliveryInfo>
</ns1:Register>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Register for SMS OTP responseRegister for SMS OTP output fields provides details about the Register for SMS OTP output fields.
63
Symantec VIP Web Services Developer's Guide
Table 37: Register for SMS OTP output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<RegisterResponse RequestId=" EICG5753" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</RegisterResponse>
</Body>
</Envelope>
Register error codesThis section lists the error codes you may encounter using the Register API.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e0a: Token orders for this token type already fulfilled or expired
4e10: This URL does not support this operation
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
Symantec VIP Web Services Developer's Guide
• 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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 38: ActivateToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
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
<?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="1234abcd">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
<ns1:OTP1>897130</ns1:OTP1>
</ns1:ActivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample ActivateToken for SMS OTP responseActivateToken for SMS OTP output fields lists the ActivateToken for SMS OTP output fields.
65
Symantec VIP Web Services Developer's Guide
Table 39: ActivateToken for SMS OTP output fields
Output Field Required? Type Purpose
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
Sample SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ActivateTokenResponse RequestId="EHBE4660" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</ActivateTokenResponse>
</Body>
</Envelope>
ActivateToken for SMS OTP error codesThis section lists the error codes you may encounter using the ActivateToken for SMS OTP API.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0a: Token orders for this token type already fulfilled or expired
4e0b: VIP certificate revoked
4e1a: Unable to send SMS to given number through gateway
4e1d: OTP needs to be supplied for a phone number in a new state
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/val/soap
Table 40: SendOTP for SMS OTP input fields
Input Field Required? Type Purpose
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"
See:
• Sample SOAP XML request• SendOTP for SMS OTP error codes
Sample 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:SendOTP Version="3.1" Id="JGBJ7818">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
</ns1:SendOTP>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample SOAP XML response<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SendOTPResponse RequestId="JGBJ7818" Version="3.1"
67
Symantec VIP Web Services Developer's Guide
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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
Output Field Required? Type Purpose
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
Sample SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SendOTPResponse RequestId="JGBJ7818" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
68
Symantec VIP Web Services Developer's Guide
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e1a: Unable to send SMS to given number through gateway
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4e17: The phone number has been deactivated by the carrier; the number must
be registered again
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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:
https://services-auth.vip.symantec.com/val/soap
Table 42: Validate for SMS OTP input fields
Input Field Required? Type Purpose
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"
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
<?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/";
69
Symantec VIP Web Services Developer's Guide
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:TokenId type="SMS">16505551212</ns1:TokenId>
<ns1:OTP>111111</ns1:OTP>
</ns1:Validate>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
ReasonCode Y hexBinary If the Validate request is unsuccessful, the ReasonCodeprovides the reason.
StatusMessage Y String States whether the Validate request was successfullycompleted.
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 codeis generated in hardware or software.
See:
• Sample Validate for SMS OTP SOAP XML response• Validate for SMS OTP error codes
70
Symantec VIP Web Services Developer's Guide
Sample Validate for SMS OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<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>
<TokenCategoryDetails>
<CategoryId>73</CategoryId>
<FormFactor>SMS</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SERVER</OtpGeneratedBy>
</TokenCategoryDetails>
</ValidateResponse>
</Body>
</Envelope>
Validate for SMS OTP error codesThis section lists the error codes you may encounter using the Validate for SMS OTP API.
See VIP Web Services error codes.
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 44: DeactivateToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
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
<?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:DeactivateToken Version="3.1" Id="HJBA0766">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
<ns1:Reason>Lost</ns1:Reason>
</ns1:DeactivateToken>
</SOAP-ENV:Body>
72
Symantec VIP Web Services Developer's Guide
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DeactivateTokenResponse RequestId="HJBA0766" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DeactivateTokenResponse>
</Body>
</Envelope>
DeactivateToken for SMS OTP error codesThis section lists the error codes you may encounter using the DeactivateToken for SMS OTPAPI.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
73
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 46: EnableToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
See Sample EnableToken for SMS OTP SOAP XML request.
Sample 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:EnableToken Version="3.1" Id="IGEC8036">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
</ns1:EnableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
See Sample EnableToken for SMS OTP SOAP XML response.
74
Symantec VIP Web Services Developer's Guide
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
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<EnableTokenResponse RequestId="IGEC8036" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</EnableTokenResponse>
</Body>
</Envelope>
EnableToken for SMS OTP error codesThis section lists the error codes you may encounter using the EnableToken for SMS OTP API.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 48: DisableToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
Reason N String Specifies the reason for disabling the credential.
Sample DisableToken for SMS OTP 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:DisableToken Version="3.1" Id="EBFC3461">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
<ns1:Reason>Stolen</ns1:Reason>
</ns1:DisableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Sample DisableToken for SMS OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DisableTokenResponse RequestId="EBFC3461" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DisableTokenResponse>
</Body>
</Envelope>
DisableToken for SMS OTP error codesThis section lists the error codes you may encounter using the DisableToken for SMS OTP API.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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
Symantec VIP Web Services Developer's Guide
Unlock for SMS OTP requestUnlockToken for SMS OTP input fields provides details about the UnlockToken for SMS OTP input field. Send the requestto:
https://services-auth.vip.symantec.com/mgmt/soap
Table 50: UnlockToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
See Sample Unlock for SMS OTP SOAP XML request.
Sample Unlock for SMS OTP 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:UnlockToken Version="3.1" Id="BGFA5527">
<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
Output Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Sample Unlock for SMS OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<UnlockTokenResponse RequestId="BGFA5527" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</UnlockTokenResponse>
</Body>
</Envelope>
UnlockToken for SMS OTP error codesThis section lists the error codes you may encounter using the UnlockToken API.
See VIP Web Services error codes.
4990: Bad Token State
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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:
https://services-auth.vip.symantec.com/mgmt/soap
79
Symantec VIP Web Services Developer's Guide
Table 52: GetTokenInformation for SMS OTP input fields
Input Field Required? Type Purpose
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"
See Sample GetTokenInformation for SMS OTP SOAP XML request.
Sample GetTokenInformation for SMS OTP 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:GetTokenInformation Version="3.1" Id="CCFD6815">
<ns1:TokenId type="SMS">16505551212</ns1:TokenId>
</ns1:GetTokenInformation>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample GetTokenInformation for SMS OTP responseGetTemporaryPwdExpiration output fields lists the GetTokenInformation for SMS OTP output fields.
Table 53: GetTemporaryPwdExpiration output fields
Output Field Required? Type Purpose
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.
TokenKind Y String Shows whether the credential is a software credential orhardware 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
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
LastUpdate Y dateTime Shows the last time that there was a call to the VIP WebServices for the credential.
Owner N boolean Shows whether the API call came from the same party thatissued 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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<GetTokenInformationResponse RequestId="CCFD6815" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenInformation>
<TokenId type="SMS">3424567</TokenId>
<TokenKind>SOFTWARE</TokenKind>
<Adapter>SMS_OTP</Adapter>
<TokenStatus>DISABLED</TokenStatus>
<ExpirationDate>2011-01-08T17:31:53.000-08:00</ExpirationDate>
<LastUpdate>2008-01-09T17:58:58.000-08:00</LastUpdate>
<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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4bf1: This operation does not support this credential type
81
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 54: UnlockToken for SMS OTP input fields
Input Field Required? Type Purpose
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"
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
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/
envelope/"
82
Symantec VIP Web Services Developer's Guide
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:SendTemporaryPassword Version="3.1" Id="AIAC6061">
<ns1:TokenId>VSMB64641212</ns1:TokenId>
<ns1:PhoneNumber>16505551212</ns1:PhoneNumber>
<ns1:GatewayAcctInfo>
<ns1:Id>1234</ns1:Id>
<ns1:Password>abcdef</ns1:Password>
</ns1:GatewayAcctInfo>
<ns1:ExpirationDate>2008-09-30T19:06:55-07:00</ns1:ExpirationDate>
<ns1:SMSDeliveryInfo>
<ns1:Message>Your one-time temporary password is _OTP_.
</ns1:Message>
</ns1:SMSDeliveryInfo>
</ns1:SendTemporaryPassword>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SendTemporaryPassword for SMS OTP responseUnlockToken for SMS OTP output fields provides details about the SendTemporaryPassword for SMS OTP output fields.
Table 55: UnlockToken for SMS OTP output fields
Output Field Required? Type Purpose
ReasonCode Y hexBinary If the request to set a temporary security code isunsuccessful, the ReasonCode indicates why the operationfailed.
StatusMessage Y String States whether the temporary security code wassuccessfully set.
See Sample SendTemporaryPassword for SMS OTP SOAP XML response.
Sample SendTemporaryPassword for SMS OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SendTemporaryPasswordResponse RequestId="BBEB4255" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</SendTemporaryPasswordResponse>
</Body>
</Envelope>
83
Symantec VIP Web Services Developer's Guide
SendTemporaryPassword for SMS OTP error codesThis section lists the error codes you may encounter using the SendTemporaryPassword for SMS OTP API.
See VIP Web Services error codes.
4953: Expiration date must be later than the current time, and no
more than 7 days from now
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e1a: Unable to send SMS to given number through gateway
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
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:
<?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:Register Id="ipsita1234" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<ns1:TokenId type="SMS">47480</ns1:TokenId>
<ns1:SMSDeliveryInfo>
<ns1:Message>Your Security code is _OTP_</ns1:Message>
</ns1:SMSDeliveryInfo>
</ns1:Register>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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:
<?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/"
85
Symantec VIP Web Services Developer's Guide
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:SendTemporaryPassword Id="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<ns1:TokenId>VSMB91146979</ns1:TokenId>
<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:SMSDeliveryInfo>
<ns1:Message>Your one-time temporary password is _OTP_.</ns1:Message>
</ns1:SMSDeliveryInfo>
</ns1:SendTemporaryPassword>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
86
Symantec VIP Web Services Developer's Guide
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.
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 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
Symantec VIP Web Services Developer's Guide
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
API Name Description See
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:
https://services-auth.vip.symantec.com/prov/soap
88
Symantec VIP Web Services Developer's Guide
Table 58: Register for Voice OTP input fields
Input Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<Register Id="1234abcd" Version="3.1" xmlns="https://schemas.vip.
symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
<ns1:DeliverOTP>true</ns1:DeliverOTP>
<VoiceDeliveryInfo>
<AuthentifyVoiceDeliveryInfo>
<Account>test_accnt</Account>
<Language>en-us</Language>
</AuthentifyVoiceDeliveryInfo>
</VoiceDeliveryInfo>
89
Symantec VIP Web Services Developer's Guide
</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
Output Field Required? Type Purpose
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 Register for Voice OTP SOAP XML response.
Sample Register for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<RegisterResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</RegisterResponse>
</Body>
</Envelope>
Register for Voice OTP error codesThis section lists the error codes you may encounter using the Register API.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e0a: Token orders for this token type already fulfilled or expired
4e10: This URL does not support this operation
4e1a: Unable to send SMS to given number through gateway
4e1b: Phone number has already been activated
90
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 60: ActivateToken for Voice OTP input fields
Input Field Required? Type Purpose
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"
OTP1 N String The VIP Web Service checks any security codes againstthe credential ID to verify the validity of the credential.
See Sample ActivateToken for Voice OTP SOAP XML request.
Sample ActivateToken for Voice OTP 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 Id="1234abcd" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
<ns1:OTP1>974427</ns1:OTP1>
</ns1:ActivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
91
Symantec VIP Web Services Developer's Guide
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
Output Field Required? Type Purpose
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 ActivateToken for Voice OTP SOAP XML response.
Sample ActivateToken for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ActivateTokenResponse RequestId="1234abcd" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</ActivateTokenResponse>
</Body>
</Envelope>
ActivateToken for Voice OTP error codesThis section lists the error codes you may encounter using the ActivateToken for Voice OTP API.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0a: Token orders for this token type already fulfilled or expired
4e0b: VIP certificate revoked
4e1a: Unable to send SMS to given number through gateway
4e1d: OTP needs to be supplied for a phone number in a new state
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4e16: Phone number was not previously registered for this account
4f05: This VIP credential or VIP credential type is not supported
for this account.
92
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/val/soap
Table 62: SendOTP for Voice OTP input fields
Input Field Required? Type Purpose
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
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 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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<SendOTP Id="1234abcd" Version="3.1" xmlns="https://schemas.
93
Symantec VIP Web Services Developer's Guide
vip.symantec.com/2006/08/vipservice">
<TokenId type="Voice" >16505551212</TokenId>
<VoiceDeliveryInfo>
<AuthentifyVoiceDeliveryInfo>
<Account>test_accnt</Account>
<Language>en-us</Language>
</AuthentifyVoiceDeliveryInfo>
</VoiceDeliveryInfo>
</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
Output Field Required? Type Purpose
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 SendOTP for Voice OTP SOAP XML response.
Sample SendOTP for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SendOTPResponse RequestId="1234abcd" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
94
Symantec VIP Web Services Developer's Guide
4e1a: Unable to send SMS to given number through gateway
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4e17: The phone number has been deactivated by the carrier; the number
must be registered again
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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.
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.
• 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:
https://services-auth.vip.symantec.com/val/soap
Table 64: Validate for Voice OTP input fields
Input Field Required? Type Purpose
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"
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 Voice OTP SOAP XML request.
Sample Validate for Voice OTP 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"
95
Symantec VIP Web Services Developer's Guide
xmlns:ns3="http://www.w3.org/2000/09/xmldsig#"
xmlns:ns1="https://schemas.vip.symantec.com/2006/08/vipservice">
<SOAP-ENV:Body>
<ns1:Validate Id="1234abcd" Version="3.1" xmlns="https://schemas.vip.
symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
<ns1:OTP>352134</ns1:OTP>
</ns1:Validate>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
ReasonCode Y hexBinary If the Validate request is unsuccessful, the ReasonCodeprovides the reason.
StatusMessage Y String States whether the Validate request was successfullycompleted.
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 codeis generated in hardware or software.
See Sample Validate for Voice OTP SOAP XML response.
Sample Validate for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ValidateResponse RequestId="1234abcd" Version="3.1"
96
Symantec VIP Web Services Developer's Guide
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenCategoryDetails>
<CategoryId>74</CategoryId>
<FormFactor>VOICE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SERVER</OtpGeneratedBy>
</TokenCategoryDetails>
</ValidateResponse>
</Body>
</Envelope>
Validate for Voice OTP error codesThis section lists the error codes you may encounter using the Validate for Voice OTP API.
See VIP Web Services error codes.
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 66: DeactivateToken for Voice OTP input fields
Input Field Required? Type Purpose
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"
Reason N String To specify the reason for deactivating the token.
See Sample DeactivateToken for Voice OTP SOAP XML request.
Sample DeactivateToken for Voice OTP 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:DeactivateToken Id="1234abcd" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
<Reason>Unspecified</Reason>
</ns1:DeactivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
98
Symantec VIP Web Services Developer's Guide
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
Output Field Required? Type Purpose
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 Voice OTP SOAP XML response.
Sample DeactivateToken for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DeactivateTokenResponse RequestId="1234abcd" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DeactivateTokenResponse>
</Body>
</Envelope>
DeactivateToken for Voice OTP error codesThis section lists the error codes you may encounter using the DeactivateToken for Voice OTPAPI.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
• 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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 68: EnableToken for Voice OTP input fields
Input Field Required? Type Purpose
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 EnableToken for Voice OTP SOAP XML request.
Sample EnableToken for Voice OTP 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:EnableToken Id="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
</ns1:EnableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
EnableToken for Voice OTP responseEnableToken for Voice OTP output fields lists the EnableToken for Voice OTP output fields.
100
Symantec VIP Web Services Developer's Guide
Table 69: EnableToken for Voice OTP output fields
Output Field Required? Type Purpose
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.
See Sample EnableToken for Voice OTP SOAP XML response.
Sample EnableToken for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<EnableTokenResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>true</SameInitialState>
</EnableTokenResponse>
</Body>
</Envelope>
EnableToken for Voice OTP error codesThis section lists the error codes you may encounter using the EnableToken for Voice OTP API.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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
Symantec VIP Web Services Developer's Guide
DisableToken for Voice OTP requestDisableToken for Voice OTP input fields provides details about the DisableToken for Voice OTP input fields. Send therequest to:
https://services-auth.vip.symantec.com/mgmt/soap
Table 70: DisableToken for Voice OTP input fields
Input Field Required? Type Purpose
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"
Reason N String Specifies the reason for disabling the credential.
See Sample DisableToken for Voice OTP SOAP XML request.
Sample DisableToken for Voice OTP 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:DisableToken Id="1234abcd" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Voice">16505551212</TokenId>
</ns1:DisableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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.
102
Symantec VIP Web Services Developer's Guide
See Sample DisableToken for Voice SOAP XML response.
Sample DisableToken for Voice SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DisableTokenResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DisableTokenResponse>
</Body>
</Envelope>
DisableToken for Voice OTP error codesThis section lists the error codes you may encounter using the DisableToken for Voice OTP API.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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:
https://services-auth.vip.symantec.com/mgmt/soap
103
Symantec VIP Web Services Developer's Guide
Table 72: GetTokenInformation for Voice OTP input fields
Input Field Required? Type Purpose
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 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/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
#soapenv:Body>
#GetTokenInformation Id="1234abcd" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
#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.
Table 73: GetTemporaryPwdExpiration output fields
Output Field Required? Type Purpose
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 theVoice credential.
TokenKind Y String Shows whether the credential is a software credential orhardware credential.
Adapter Y String Shows the credential type: Voice_OTPTokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,
Locked, or New).See Credential states.
ExpirationDate Y dateTime Shows the credential expiration date.
104
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
LastUpdate Y dateTime Shows the last time that there was a call to the VIP WebServices for the credential.
Owner N boolean Shows whether the API call came from the same party thatissued the credential.
ReportedReason N String Shows the reported reason for this token ID.
See Sample GetTokenInformation for Voice OTP SOAP XML response.
Sample GetTokenInformation for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<GetTokenInformationResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenInformation>
<TokenId type="Voice">16505551212</TokenId>
<TokenKind>SOFTWARE</TokenKind>
<Adapter>VOICE_OTP</Adapter>
<TokenStatus>ENABLED</TokenStatus>
<ExpirationDate>2012-08-03T23:13:04.000-07:00</ExpirationDate>
<LastUpdate>2009-08-05T16:20:20.000-07:00</LastUpdate>
<Owner>true</Owner>
</TokenInformation>
</GetTokenInformationResponse>
</Body>
/Envelope>
GetTokenInformation for Voice OTP error codesThis section lists the error codes you may encounter using the GetTokenInformation for Voice OTP API.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4bf1: This operation does not support this credential type
105
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 74: SendTemporaryPassword for Voice OTP input fields
Input Field Required? Type Purpose
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
Symantec VIP Web Services Developer's Guide
Input Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<SendTemporaryPassword Version="3.1" xmlns="https://schemas.vip.
symantec.com/2006/08/vipservice">
<TokenId>1234abcd</TokenId>
<Destination type="Voice">16505551212</Destination>
<ExpirationDate>2009-08-07T13:52:34.625-07:00</ExpirationDate>
<VoiceDeliveryInfo>
<AuthentifyVoiceDeliveryInfo>
<Account>test_acct</Account>
<Language>en-us</Language>
</AuthentifyVoiceDeliveryInfo>
</VoiceDeliveryInfo>
</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
Output Field Required? Type Purpose
ReasonCode Y hexBinary If the request to set a temporary security code isunsuccessful, the ReasonCode indicates why the operationfailed.
StatusMessage Y String States whether the temporary security code wassuccessfully set.
107
Symantec VIP Web Services Developer's Guide
See Sample SendTemporaryPassword for Voice OTP SOAP XML response.
Sample SendTemporaryPassword for Voice OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SendTemporaryPasswordResponse Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4953: Expiration date must be later than the current time, and no
more than 7 days from now
4994: Operation not allowed on a locked token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e1a: Unable to send SMS to given number through gateway
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/mgmt/soap
Table 76: UnlockToken for Voice OTP input fields
Input Field Required? Type Purpose
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 Unlock for Voice OTP SOAP XML request.
Sample Unlock for Voice OTP SOAP XML request
</SOAP-ENV:Envelope>
<?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:UnlockToken Version="3.1" Id="BGFA5527">
<ns1:TokenId type="Voice">VSMB57361338</ns1:TokenId>
</ns1:UnlockToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Unlock for Voice OTP responseUnlockToken for SMS OTP output fields provides details about the UnlockToken for Voice OTP output fields.
109
Symantec VIP Web Services Developer's Guide
Table 77: UnlockToken for SMS OTP output fields
Output Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<UnlockTokenResponse RequestId="BGFA5527" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</UnlockTokenResponse>
</Body>
</Envelope>
UnlockToken error codesThis section lists the error codes you may encounter using the UnlockToken API.
See VIP Web Services error codes.
4990: Bad Token State
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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
Symantec VIP Web Services Developer's Guide
• 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
Symantec VIP Web Services Developer's Guide
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.
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 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
Symantec VIP Web Services Developer's Guide
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
API Name Description See
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:
https://services-auth.vip.symantec.com/prov/soap
113
Symantec VIP Web Services Developer's Guide
Table 79: Register for Service-generated OTP input fields
Input Field Required? Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<Register Id="V0ePCaAoyq" Version="3.1" xmlns="https://schemas.vip.
symantec.com/2006/08/vipservice">
<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
Output Field Required? Type Purpose
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 Register for Service-generated OTP SOAP XML response.
Sample Register for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<RegisterResponse RequestId="V0ePCaAoyq" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<Status>
114
Symantec VIP Web Services Developer's Guide
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e0a: Token orders for this token type already fulfilled or expired
4e10: This URL does not support this operation
4e1a: Unable to send SMS to given number through gateway
4e1b: Phone number has already been activated
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:
https://services-auth.vip.symantec.com/mgmt/soap
115
Symantec VIP Web Services Developer's Guide
Table 81: ActivateToken for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
OTP1 N String The VIP Web Service checks any security codes againstthe credential ID to verify the validity of the credential.
See Sample ActivateToken for Service-generated OTP SOAP XML request.
Sample ActivateToken for Service-generated OTP 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 Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service">491761212</TokenId>
<ns1:OTP1>507638</ns1:OTP1>
</ns1:ActivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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 ActivateToken for Service-generated OTP SOAP XML response.
116
Symantec VIP Web Services Developer's Guide
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"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
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.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
49b5: Failed with an invalid security code
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0a: Token orders for this token type already fulfilled or expired
4e0b: VIP certificate revoked
4e1a: Unable to send SMS to given number through gateway
4e1d: OTP needs to be supplied for a phone number in a new state
4e10: This URL does not support this operation
4e11: Token ID has been revoked
4e16: Phone number was not previously registered for this account
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
Symantec VIP Web Services Developer's Guide
https://services-auth.vip.symantec.com/val/soap
Table 83: SendOTP for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
See Sample SendOTP for Service-generated OTP SOAP XML request.
Sample SendOTP for Service-generated OTP SOAP XML request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<SendOTP Id="abcd1cd1234" Version="3.1" xmlns="https://schemas.vip.
symantec.com/2006/08/vipservice">
<TokenId type="Service" >491761212</TokenId>
</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
Output Field Required? Type Purpose
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 SendOTP for Service-generated OTP SOAP XML response.
Sample SendOTP for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
118
Symantec VIP Web Services Developer's Guide
<Body>
<SendOTPResponse RequestId="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e1a: Unable to send SMS to given number through gateway
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4e17: The phone number has been deactivated by the carrier; the
number must be registered again
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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.
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.
• 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:
https://services-auth.vip.symantec.com/val/soap
119
Symantec VIP Web Services Developer's Guide
Table 85: Validate for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
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 Service-generated OTP SOAP XML request.
Sample Validate for Service-generated OTP 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:Validate Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service">491761212</TokenId>
<ns1:OTP>645953</ns1:OTP>
</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
Output Field Required? Type Purpose
ReasonCode Y hexBinary If the Validate request is unsuccessful, the ReasonCodeprovides the reason.
StatusMessage Y String States whether the Validate request was successfullycompleted.
120
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
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 codeis generated in hardware or software.
See Sample Validate for Service-generated OTP SOAP XML response.
Sample Validate for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<ValidateResponse RequestId="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenCategoryDetails>
<CategoryId>75</CategoryId>
<FormFactor>SERVICE</FormFactor>
<MovingFactor>EVENT</MovingFactor>
<OtpGeneratedBy>SERVER</OtpGeneratedBy>
</TokenCategoryDetails>
</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.
See VIP Web Services error codes.
49b5: Failed with an invalid security code
121
Symantec VIP Web Services Developer's Guide
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
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:
https://services-auth.vip.symantec.com/mgmt/soap
122
Symantec VIP Web Services Developer's Guide
Table 87: DeactivateToken for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
Reason N String To specify the reason for deactivating the token.
See Sample DeactivateToken for Service-generated OTP SOAP XML request.
Sample DeactivateToken for Service-generated OTP 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:DeactivateToken Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service">identifier1</TokenId>
<Reason>Unspecified</Reason>
</ns1:DeactivateToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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 Service-generated OTP SOAP XML response.
123
Symantec VIP Web Services Developer's Guide
Sample DeactivateToken for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DeactivateTokenResponse RequestId="abcd1cd1234" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DeactivateTokenResponse>
</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.
See VIP Web Services error codes.
4993: Operation not allowed on a disabled token
4995: Operation not allowed on a new token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e11: Token ID has been revoked
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:
https://services-auth.vip.symantec.com/mgmt/soap
124
Symantec VIP Web Services Developer's Guide
Table 89: EnableToken for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
See Sample EnableToken for Service-generated OTP SOAP XML request.
Sample EnableToken for Service-generated OTP 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:EnableToken Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service">491761212</TokenId>
</ns1:EnableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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.
See Sample EnableToken for Service-generated OTP SOAP XML response.
Sample EnableToken for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
125
Symantec VIP Web Services Developer's Guide
<Body>
<EnableTokenResponse RequestId="abcd1cd1234" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>true</SameInitialState>
</EnableTokenResponse>
</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.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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:
https://services-auth.vip.symantec.com/mgmt/soap
126
Symantec VIP Web Services Developer's Guide
Table 91: DisableToken for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
Reason N String Specifies the reason for disabling the credential.
See Sample DisableToken for Service-generated OTP SOAP XML request.
Sample DisableToken for Service-generated OTP 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:DisableToken Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service">491764112</TokenId>
</ns1:DisableToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
Output Field Required? Type Purpose
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.
See Sample DisableToken for Service-generated OTP SOAP XML response.
Sample DisableToken for Service-generated OTP SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
127
Symantec VIP Web Services Developer's Guide
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DisableTokenResponse RequestId="abcd1cd1234" Version="3.1" xmlns=
"https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SameInitialState>false</SameInitialState>
</DisableTokenResponse>
</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.
See VIP Web Services error codes.
4995: Operation not allowed on a new token
4996: Operation not allowed on an inactive token
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
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:
https://services-auth.vip.symantec.com/mgmt/soap
128
Symantec VIP Web Services Developer's Guide
Table 93: GetTokenInformation for Service-generated OTP input fields
Input Field Required? Type Purpose
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"
See Sample GetTokenInformation for Service-generated OTP SOAP XML request.
Sample GetTokenInformation for Service-generated OTP SOAP XML request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<GetTokenInformation Id="abcd1cd1234" Version="3.1" xmlns="https://
schemas.vip.symantec.com/2006/08/vipservice">
<TokenId type="Service" >16505551212</TokenId>
</GetTokenInformation>
</soapenv:Body>
</soapenv:Envelope>
GetTokenInformation for Service-generated OTP responseGetTemporaryPwdExpiration output fields lists the GetTokenInformation for Service-generated OTP output fields.
Table 94: GetTemporaryPwdExpiration output fields
Output Field Required? Type Purpose
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 theService-generated credential.
TokenKind Y String Shows whether the credential is a software credential orhardware credential.
Adapter Y String Shows the credential type: SERVER_OTPTokenStatus Y String Shows the credential state (Enabled, Disabled, Inactive,
Locked, or New).See Credential states.
ExpirationDate Y dateTime Shows the credential expiration date.
129
Symantec VIP Web Services Developer's Guide
Output Field Required? Type Purpose
LastUpdate Y dateTime Shows the last time that there was a call to the VIP WebServices for the credential.
Owner N boolean Shows whether the API call came from the same party thatissued the credential.
ReportedReason N String Shows the reported reason for this token ID.
See Sample GetTokenInformation for Service-generated OTP SOAP XML response.
Sample GetTokenInformation for Service-generated OTP SOAP XML response
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<GetTokenInformationResponse RequestId="V0ePCaAoyq" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
<TokenInformation>
<TokenId type="Service">IDENTIFIER1</TokenId>
<TokenKind>SOFTWARE</TokenKind>
<Adapter>SERVER_OTP</Adapter>
<TokenStatus>DISABLED</TokenStatus>
<ExpirationDate>2012-08-03T23:26:21.000-07:00</ExpirationDate>
<LastUpdate>2009-08-05T16:05:20.000-07:00</LastUpdate>
<Owner>true</Owner>
<ReportedReason>Unspecified</ReportedReason>
</TokenInformation>
</GetTokenInformationResponse>
</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.
See VIP Web Services error codes.
4e00: Malformed request
4e01: Service Internal Error
4e02: Authentication failed
4e03: Authorization failed
4e04: Unsupported service protocol version
4e0b: VIP certificate revoked
4e10: This URL does not support this operation
4e16: Phone number was not previously registered for this account
4bf1: This operation does not support this credential type
130
Symantec VIP Web Services Developer's Guide
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.
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
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
To customize out-of-band authentication with additional parameters for your own particular needs, contact your Symantecrepresentative.
The following APIs are provided for out-of-band authentication:
Table 95: Out-of-band authentication APIs
API Name Description See
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
Symantec VIP Web Services Developer's Guide
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
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 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
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<SubmitTxnVerification Id="31Ct8H5KOU" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<PhoneNumber>19999999999</PhoneNumber>
<TxnOTP>468888</TxnOTP>
<Language>en-us</Language>
<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
Symantec VIP Web Services Developer's Guide
</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"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<SubmitTxnVerificationResponse RequestId="31Ct8H5KOU" Version
="2.0"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>4E21</ReasonCode>
<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.
4845: The request parameters you supplied contain an unexpected value
or format.
4e01: Service internal error.
4e03: Authorization failed.
4e21: Unable to send message to voice gateway for the given number.
135
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/txn/soap
Table 98: PollTxnVerification input fields
Input Field Required Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<PollTxnVerification Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<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
Output Field Required Type Purpose
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
Symantec VIP Web Services Developer's Guide
Sample Poll for voice call completion SOAP XML response
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<PollTxnVerificationResponse Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>4E21</ReasonCode>
<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.
4845: The request parameters you supplied contain an unexpected value
or format.
4e01: Service internal error.
4e03: Authorization failed.
4e21: Unable to send message to voice gateway for the given number.
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
Symantec VIP Web Services Developer's Guide
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:
https://services-auth.vip.symantec.com/txn/soap
138
Symantec VIP Web Services Developer's Guide
Table 100: DeliverTxnOTP input fields
Input Field Required Type Purpose
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
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 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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<DeliverTxnOTP Version="3.1" Id="1234abcd"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<TxnOTP>123456</TxnOTP>
<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
Output Field Required Type Purpose
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
Symantec VIP Web Services Developer's Guide
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
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<DeliverTxnOTPResponse RequestId="1234abcd" Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</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.
4845: The request parameters you supplied contain an unexpected value
or format.
4e01: Service internal error.
4e03: Authorization failed.
4e1a: Unable to send SMS to given number through gateway.
4e21: Unable to send message to voice gateway for the given number.
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:
https://services-auth.vip.symantec.com/txn/soap
Table 102: VerifyTxnOTP input fields
Input Field Required Type Purpose
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
Symantec VIP Web Services Developer's Guide
Sample Verify security code SOAP XML request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<VerifyTxnOTP Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<TxnId>601B82D6E9AA8128</TxnId>
<TxnOTP>123456</TxnOTP>
</VerifyTxnOTP>
</soapenv:Body>
</soapenv:Envelope>
Verify security code responseVerifyTxnOTP output fields provides details about the VerifyTxnOTP output fields.
Table 103: VerifyTxnOTP output fields
Output Field Required Type Purpose
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
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<VerifyTxnOTPResponse Version="3.1"
xmlns="https://schemas.vip.symantec.com/2006/08/vipservice">
<Status>
<ReasonCode>0000</ReasonCode>
<StatusMessage>Success</StatusMessage>
</Status>
</VerifyTxnOTPResponse>
</Body>
</Envelope>
Verify security code error codesYou may possibly encounter the following error codes using the VerifyTxnOTP API.
4845: The request parameters you supplied contain an unexpected value
or format.
4e01: Service internal error.
4e03: Authorization failed.
4e3a: Invalid user input.
141
Symantec VIP Web Services Developer's Guide
4e3f: Security code expired.
142
Symantec VIP Web Services Developer's Guide
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.
See Setting and managing temporary securitycodes.
4953 Expiration must be later than the current time, andno more than seven days from now.
See Setting and managing temporary securitycodes.
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
Symantec VIP Web Services Developer's Guide
Error Code Cause Solution
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
Symantec VIP Web Services Developer's Guide
Error Code Cause Solution
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
Symantec VIP Web Services Developer's Guide
Error Code Cause Solution
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
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
Symantec VIP Web Services Developer's Guide
151
Symantec VIP Web Services Developer's Guide
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