Authenticate

The Authenticate Web Service, an optional service, provides your application with the ability to authenticate a user without using SAML. For example, your application can ask a user to supply his or her password to certify a form submission, or can generate an e-Signature. Learn about Web Services.

NOTE: The info on this page relates to the "default" Authenticate Web Service. If your application requires the authenticated user's GUID, follow the instructions on the Authenticate v2 page instead.

! IMPORTANT: This service can not be used to authenticate social identities.

 

Authenticate Web Service (Deprecated)

Your application may use this service to authenticate a user.

POST /account/api/authenticate.htm

Input

Parameter Name	Parameter Description	Optional/ Required
email	The user's email address (i.e., "mail") from the SAML Assertion. The domain part of the user's email address may be omitted if it equals "noemail.nyc.gov".	Required
password	The user's password	Required
dateTime	The current date and time formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm).	Optional, unless your application's NYC.ID Service Account is configured to prevent replay attacks
userName	Your application's NYC.ID Service Account username	Required
signature	The signature generated for this request. Refer to calculating the authentication signature	Required

Output

Http Status (Code)	Response	Description
OK (200)	{"authenticated":true}	Indicates the supplied email address and password were correct
OK (200)	{"authenticated":false}	Indicates the supplied email address and password were incorrect
OK (200)	{"authenticated":"locked"}	Indicates the user account is locked
BAD REQUEST (400)	Refer to Bad Request Status table below	Indicates there was an error in the http request
UNAUTHORIZED (401)	Refer to Unauthorized Status table below	Indicates there was an error in the http request related to authentication
INTERNAL SERVER ERROR (500)	Refer to Internal Server Error Status table below	Indicates there was an error while processing the http request
SERVICE UNAVAILABLE (503)	Not Applicable	Indicates the server is undergoing maintenance and is temporarily unavailable

Bad Request Status

A bad request status indicates there was a problem with the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Here is a sample error:

{"ERRORS":{"email":"invalid","password":"required","userName":"required","signature":"required"}}

Code	Message	Description
email	invalid	email address was not provided or was invalid.
password	required	"password" was not provided.
userName	invalid	"userName" was not provided or was invalid.
signature	invalid	"signature" was not provided or was not in the required format.

Unauthorized Status

An unauthorized status indicates there was a problem with the http request related to authentication. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Here is a sample error:

{"ERRORS":{"cpui.failedToAuthenticate":"The combination of userName and signature is incorrect."}}

Code	Message	Description
cpui.invalidDomainName	Invalid Domain Name: <domainName>. Valid Domains: [doitt.nycnet, nyc.gov, nycid.nycnet, csc.nycnet, cloudapp.net, hpd.nycnet, nycgovparks.org, finance.nycnet, hpdnyc.org, cs.nycnet, gcomsoft.com, records.nycnet, dcas.nycnet, dhs.nycnet, redcapcloud.com, cityofnewyork.us, dynamics.com, dynamics365portals.us, getinfo.nyc, fdnycloud.org, microsoftonline.com, mkscloud.com, samaritan.com, ivalua.us, sbs.nycnet, communityneeds.nyc, ukrosoft.com.ua, appgeo.com, azurewebsites.net, or gigya.com]	The referrer domain name was invalid.
cpui.failedToAuthenticate	The combination of userName and signature is incorrect.	Authentication failed. Either "userName" or "signature" was incorrect or "dateTime", if provided, differs by more than 15 minutes from the current date and time.

Internal Server Error Status

An internal server error status indicates there was a problem while processing the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Code	Message	Description
cpui.exception	This value is dynamically computed based on the cause of the error. For those that are curious, it's the output of the getMessage() method of the java.lang.Exception class.	Indicates an unknown error occurred while processing the request