Most of the resources available through the Kiva API are public and unprotected. In fact, most of the data about our partners, lenders, and borrowers is made public as we strive to make lending as transparent as possible. As a result, most apps only need access to public data from the Kiva API to build compelling experiences. However when a developer wishes for a part of his application to target a specific Kiva customer (usually, a Kiva lender) then it can be interesting to broker access for the user to his private account data via the Kiva API by accessing protected resources.
Applications wanting to access protected resources should consider very carefully how they will use private data in their application. Even the most well-intentioned applications could violate the user's expectations around how their data is handled simply through poor design. Moreover, inadequate privacy measures, poor knowledge of network security issues, lazy coding, and bugs can expose private data and violate a user's trust. We take our user's privacy very seriously and we require the same approach to user data from our developers. As such, we've devote the first few topics here to guide you in designing and implementing secure, responsible applications. Applications that handle user private data poorly weaken the Kiva community and are very likely a violation of the Kiva and Kiva API terms of service.
Private user data is protected via OAuth in the Kiva API. OAuth is an industry standard mechanism by which a user can delegate and control access to protected resources on the Internet to applications that request it. Your application issues such a request directly to the user via the Kiva API and if the request is approved, your application is immediately issued special access credentials by Kiva. It's important to note that the user can revoke these credentials at any time. Accessing protected resources in the Kiva API requires a working knowledge of the related OAuth standards we've employed, including OAuth 1.0a, MAC tokens, and HTTPS. Fortunately, we've included a wealth of information here to refresh the veterans and to get newbies up to speed.
Kiva uses OAuth 1.0a to control application access to protected resources. OAuth is an industry standard that allows a user to authorize an application to act their behalf with certain permissions. OAuth gives the user a great deal of control and security in that the application never has full access to their account, passwords, or other credentials and that the user can revoke the application's access to their account any time using their Kiva account preferences.
Using protected resources demands skill and caution. But, with a little effort, they can be a powerful addition to your app. If you're up to the challenge, continue on…
To use the OAuth protocol you are required to store secret tokens. Your app will be issues a client secret and you will be granted an access token secret for each user. You must be able to store these securely in your application. If your app writes to databases on client devices, such as mobile phones, you must encrypt any token secrets you store. If you how don't do this, your app will be insecure and expose your apps users to having their private Kiva data exposed. If you are unsure how to encrypt data on your platform, post in the forum.
We can’t stress enough how important it is to us to protect the private data of our users. If your app is granted access to such data by a user, we expect you to take the same approach. Kiva user private data can include sensitive identifying information such as name, physical location or email address, as well as financial details such account balances, loan transaction, monetary losses, and gifts to other individuals. It could even include data confidential between a borrower and the lenders to a loan. That Kiva deals with personal financial data and financial transactions between users ups the ante for everyone. It's important that developers accessing such data respect user privacy and make the proper efforts to protect it.How do I know what data is private?
The types of private data accessible to developers may fluctuate as we deploy new release of the API. To keep things simple, we define private data as any resource that can be accessed or modified under these URL prefixes:
Thus, if you accessed data from an endpoint prefixed by either of these URL paths, you should treat that data as private. Some of the same information may be available through other Kiva APIs (e.g., location, number of loans, name) but you can never be certain if the user has hidden this information in their public profile unless you also access the data from a public URL. Therefore, when you access data from a protected URL, keep it private. If you want to display data about a user (or partner) publicly, access a public URL instead.How should private data be used in my application?
Private data should be viewed and used only by the user to whom it belongs. This means your application should be designed in such a way that access can be protected from users other than the owner. There are also important security measures that every application should take. As a guiding rule, if your applications accesses protected Kiva resources, you should protect these resources & data with same vigilance as Kiva. While not an exhaustive list, here's a checklist that should help make sure we're on the same page:
These are just a few of guidelines to get you started in thinking about how private data will be incorporated into your app. Before we dig deeper into best practices and security guidelines, it first helps to understand how applications are authorized to use protected resources, and how they authenticate with Kiva after authorization.
Once your application is granted an access token, it is easy to then access protected resources on behalf of a Kiva User or a Kiva Partner. The process is as simple as generating an Authorization header for your resource request using the token and adding it to the Authentication header for your HTTPS request.
We strongly recommend that you use an existing library or open source code that is well tested to sign your requests. If you are writing your own implementation, it is essential that you also review the official documentation.
A Kiva User is simply someone who has an account on Kiva and is able to make actions on Kiva such as make a loan, buy a gift card, send another user a message, or join a lending team. Typically, Kiva Users also opt to have a public profile page. Most users are Kiva Lenders, but it is important to distinguish that "lender" may only be one role of a particular Kiva User and, in fact, not all Kiva users may participate in lending. Some Kiva Users may only participate in administrative tasks such as posting or translating loans or managing a lending team.
The main private resource for users is their account information:
When requested using a valid OAuth access token, this resource (available as HTML, JSON, or XML) is returned as a data structure , similar to a Lender object, having these properties:
Here's an example of a User Account object in JSON