Weigh email-verification

[gbinal]

cc @NoahKunin

[NoahKunin]

Since we're already using the Mandrill backend, my anticipation is that getting a similar sign-up flow to MailChimp or anything else (click the link in your email to confirm) shouldn't be too difficult.

[nvembar]

I think that having a basic email confirm is at least a basic barrier to some of the problematic usage of our API we've seen lately. It's obviously not a definition solution, but even a little bit of a barrier would help avoid us from having some people try to get around our user limits. cc @pammiller0

[GUI]

Sorry for the delay chiming in, but thanks for the feedback! We'd definitely like to figure out how all the api.data.gov stakeholders would like the API key signup process to work.

For a bit more context on this issue, the way api.data.gov currently works is that if you give us a name and e-mail address, we'll give you an API key you can immediately start using. We don't currently verify the e-mail address before doling out an api key. This lack of e-mail verification was actually a purposeful decision born out of early requirements for the system and a general desire to lower the barrier to entry for consuming APIs as low as possible. That being said, we're more than happy to consider alternatives. We also want to make sure that whatever approach we take doesn't cause any headaches for you.

If we do want to begin e-mail verification, I think we just have to take some care in how we roll that out. We would probably need to make it an option for each agency API owner to choose (rather than us suddenly requiring e-mail verification for all agencies using api.data.gov). Because I think we do have some API owners that feel more strongly about not requiring e-mail address verification (and some that don't want API keys at all). And purely from a user perspective, we have heard that that some users do like the immediacy of our current signup process.

I will mention that if the main driver of this is potential API abuse, in terms of overall usage, I don't think we've experienced a ton of abuse over the years despite our lack of e-mail verification. I think there have only been 2 incidents in the past year with api.data.gov abuse (and one of them was using legitimate e-mail addresses, so it wouldn't have been helped by this). And in the past 5 years at NREL, with 16,000 key signups, we haven't actually had any abuse incidents with a nearly identical no verification signup. That being said, I certainly understand some APIs will be more of a target for abuse than others, and I'm also sensitive to any unexpected abuse being a bad thing. So again, I think we're certainly open to this kind of e-mail verification, but I just want to double check that an alternative like IP-based rate limits wouldn't be preferable for you (I think I had e-mailed about this earlier, but for this past incident, an IP-based limit may have not totally solved the abuse, but it may have dramatically cut down on it--let me know if you'd like any help adding an IP limit to your API in the api.data.gov admin).

And here are some random thoughts more on the implementation and details of how we might implement e-mail verification:

• I'm envisioning this as a setting in the admin where you could basically pick what level of user verification you want to require for accessing your APIs (no api key, unverified api key, or verified e-mail address api key).
• The setting could even be tweaked on a more granular basis, so you may decide that for specific APIs, or perhaps something like POST access, you'll require a verified e-mail address API key, but for general access, you may be okay with unverified e-mail addresses.
• By making it a per API setting, we could still allow agencies that don't want to bother with e-mail verification to continue operating the way they are, but other API owners could start requiring e-mail verification for their specific APIs.
• How should we handle existing API keys to APIs that start requiring e-mail verification? Should we consider all existing API keys to be verified and only apply this e-mail verification for new signups? Or would we break all the existing keys and essentially require users re-signup to verify their e-mail address for accessing these APIs?
• We'd have to consider how this would affect our current signup process. The first thing that would change would be the confirmation page the user receives after hitting submit (this would obviously have to change from an immediate usage example using their API key to instructions on verifying their e-mail first). The other thing to figure out is how we then handle the e-mail confirmation flow with respect to signup forms being embedded on other agency developer portals. The e-mail confirmation process needs would need to interact with our servers first to verify the e-mail address, but then we need to redirect them back to some landing on the agency's documentation site with the API key information included (and this page on the agency's site would preferably be something we could handle with a similar embedded snippet like the signup form, so that would could provide a default page for agencies wanting to do this).
• We'd need to think about how this affects the usage of API keys across different agency APIs that use api.data.gov. I think it would all basically work, but we just need to consider the use-case of someone signing up for an api key on an agency that doesn't require e-mail verification and then trying to use that against an agency's API that does require e-mail verification. How do we instruct that person that they need to verify their e-mail address?

[GUI]

Related to this, we have previously given some thought to having more of a user account concept:

#72
NREL/api-umbrella#84

While e-mail verification would be part of a true user account system, I think it's worth noting that these user account ideas extend a bit beyond just performing e-mail verification. Instead, they would give users an account with credentials that they could login with. This would allow users to manage multiple api keys and view analytics on their own keys. This type of more complete user account system would obviously be larger in scope than just performing e-mail verification, but if we do decide there's a need for e-mail verification, I'd probably prefer to see that done as part of a more complete (but still optional) user account implementation. The reason is that I think if we're going to make the effort to have verified accounts, is see user accounts as more of the real end-goal, while a simpler e-mail only verification would be more of a stopgap. Real accounts could also make it worth it for end-users by providing some functionality like user-facing analytics and easier management of multiple application key (both of which have periodically been requested by users and would be nice to have).

But anyway, I just wanted to make sure to tie this issue to those couple of existing issues on user accounts, since I had forgotten to mention their possible relationship earlier.

[nvembar]

I think that this would be a strong set of features for us, at least. We want to use Umbrella, but we may not be able to without some of these features. Though most of our capabilities are about open data, which means we do want the least barrier to entry, if we want to do write APIs, we need to have a bit more control over the accounts which can and can't write to our data sets. The initial step of having the email verification was a low bar over which wanted to avoid some basic abuse (fully acknowledging it wasn't a "real" way to prevent abuse by any means).

[gbinal]

@nvembar - In the use case you describe (write APIs), I'd already recommend you manually manage key access, which you could do with the current setup. If it's a very small number of developers who'd get write access, you could lock down signup entirely and just create the handful of keys to distribute personally. If it needs to be at least open to signup, I'd suggest following the example of whitehouse.gov/developers. The terms are laid out in advance and developers must email to request a key and then your team processes the request, generates the key, and sends it to the requester if appropriate. In both cases, there's not a direct 'sign up and receive a write api key' option, nor would I think you'd want there to be regardless.

[nvembar]

@gbinal Agreed. That's definitely the model we were looking towards. I'm more looking at that from the administration side - ease of use on our side once we have those keys set up, etc, so we can keep track of those users and link them directly to the API management system. For IAE, when we do write APIs, we're going to want to get a signed agreement in place given the type of data we have to manage.

[GUI]

@nvembar, @pammiller0: We have just rolled out an optional new feature to provide e-mail verification for new API key accounts. If you want to enable it for your API, you'll need to make two small tweaks, one to your signup form and one to your API backend configuration in the api.data.gov admin. You can see this issue for a bit more detail of how to enable it or how it all works: #225

But definitely feel free to reach out if you have any questions or would like to see this behave differently. We'd welcome any feedback.