Authenticate v2

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: If your application does not allow usernames, follow the instructions on the Authenticate v3 page instead.
! IMPORTANT: This service can not be used to authenticate social identities.

 

Authenticate v2 Web Service

Your application may use this service to authenticate a user.

POST /account/api/authenticate.htm Accept application/vnd.nyc.v2

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, "user": {<user>}} Indicates the supplied email address and password were correct, and the JSON-formatted authenticated user is returned.
OK (200) {"authenticated":true, "user": {<user>}, "reason":"pending"} Indicates the supplied email address and password were correct, the user account does not have a security question and answer or has not accepted the latest terms of use, and the JSON-formatted authenticated user is returned.
OK (200) {"authenticated":false} Indicates the supplied email address and password were incorrect
OK (200) {"authenticated":"false", "reason":"locked"} Indicates the user account is locked
OK (200) {"authenticated":"false", "reason":"notFound"} Indicates the user account was not found
! IMPORTANT: This error will also be returned when a user does not have a NYC.gov account linked to his or her social account. A user may add a NYC.gov account by resetting his or her password. Learn more about Forgot Password.
! IMPORTANT: This error will also be returned when a NYC employee has not yet logged in via the NYC Employees button.
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