Authenticate v3
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 allows usernames, follow the instructions on the Authenticate v2 page instead.
! IMPORTANT: This service can not be used to authenticate social identities.
Authenticate v3 Web Service
Your application may use this service to authenticate a user.
POST /account/api/authenticate.htm Accept application/vnd.nyc.v3
Input
| Parameter Name | Parameter Description | Optional/ Required |
|---|---|---|
| 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 |
| captchaResponse | The Google reCAPTCHA v2 g-recaptcha-response string | Required after 5 failed authentication attempts |
| 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 that the user has a validated email address. 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":"wrongCaptcha"} |
Indicates the supplied captchaResponse was not provided or was incorrect! IMPORTANT: Use one of these reCAPTCHA v2 Site Keys to render the reCAPTCHA widget: ! IMPORTANT: When rendering the reCAPTCHA widget, if you receive an error that reads, "Invalid domain for site key", please contact nycidintegration@doitt.nyc.gov to have your domain registered with the Site Key.Learn more about Google reCAPTCHA v2 |
| 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. |
| OK (200) | {"authenticated":"false", "reason":"pending"} |
Indicates the user account does not have a security question and answer or has not accepted the latest terms of use |
| OK (200) | {"authenticated":"false", "reason":"unvalidated"} |
Indicates the user's email address is un-validated |
| 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 |
|---|---|---|
| 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 |