Implement optional e-mail verification requirements for API access

[GUI]

We had a rather insistent abuser of one of our APIs that kept creating a deluge of API keys under fake e-mail addresses, and didn't respond to our normal attempts to contact them or block their accounts or IP addresses (they were originally using Tor to mask their IPs, and then moved to a variety of cloud providers under new IPs). In order to deal with this, we've added e-mail verification as an option for specific agency APIs.

The solution to e-mail verification we came with is simplistic, but it ensures we don't break backwards compatibility with any existing agency usage of our signup form or signup API (which was important so we could roll this out quickly). In short, if e-mail verification is enabled, we shift to e-mailing API keys to users, instead of displaying it to them immediately. So we're not really creating bonafide user accounts with passwords, etc, but instead we're simply considering the e-mail verified if they were able to successfully receive the API key via e-mail.

Here's how it all works in a bit more detail and how agencies can go about getting it setup:

• Agency's will need to adjust their signup form to enable the verifyEmail: true option in their signup embed code snippet.
  • This setting will change the behavior of the signup form. Instead of giving the API key to the user immediately on the web page, the API key will only be e-mailed to the user, and not returned on the web page. The example URLs are also removed from the web page version of the signup page confirmation (since they don't have their key yet). The e-mail message content remains unchanged, and the key is available for immediate use upon receiving the e-mail (which hopefully shouldn't take more than a minute).
• Agencies must also adjust their API Backend in the api.data.gov admin and change the "API Key Verification Requirements" under "Global Request Settings."
  • The best choice for agencies wanting to enable this is likely the "E-mail verification transition" option. That will ensure existing API keys will continue to work (even though we don't really know if they contain valid e-mails), but moving forward only API keys created from a signup form with e-mail verification will work for this specific API. Since api.data.gov API keys can work across participating agency APIs, this is necessary so that a user can't get a key from an agency that doesn't require e-mail verification and use it on your API where you want to enforce e-mail verification.

The last bit gets at a slight wrinkle with how api keys work across agencies: If a user signs up for an API key at an agency that doesn't require e-mail verification, they won't be able to use that API key to access an API that does require e-mail verification They will instead receive an error telling them that their API key is unverified and to contact us for support. We don't currently have a way to verify the e-mail address for an existing API key, since our current mechanism relies solely on the signup process being altered (and by not returning the api key in the browser, we then consider the e-mail address verified). We could certainly explore other options for verifying existing API keys if needs be, but since we haven't seen a great deal of cross-agency API key usage by end-users to date, and we've only enabled this API key verification for 1 API so far, I think we'll wait to see how all this pans out before going further. In the meantime, users can always signup for a new API key at the agency's site that does require e-mail verification, or they can still reach out, and we can manually verify accounts if needs be.

[GUI]

Implemented in:

• NREL/api-umbrella-gatekeeper@b045c2f
• NREL/api-umbrella-web@509e706
• 23a70d9