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: [[an error occurred while processing this directive]] 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