Fetching Data

Protected Resources

Accessing & Using Protected Resources

Introduction

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…

Storing Secrets Securely

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.

Private Data & Your App

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:

https://api.kivaws.org/v1/my
https://api.kivaws.org/partner

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:

  1. Use HTTPS/SSL - Most applications will transfer application code, data and user data over the public Internet. Just as all protected resources of the Kiva API are only available over HTTPS your application should only use HTTPS (or similarly SSL-secured connections) when transferring data between your server and the browser or native client.
  2. Web apps need user authentication - If your app displays or manages private user data at a long-lived URL accessible on the public internet, you must secure access to that URL with appropriate authentication. In most cases this means requiring login with a username/password or using a trusted sign-on provider such as Facebook, Twitter, or Kiva itself.
  3. Avoid caching private data - Network traffic is often cached at some level without our control. But, you can prevent exposure to data leaks by limited how much you actively cache data for a user. Apps can cache data in cookies, local browser storage, hard disks, or other app sandboxes. In doing so, you increase the chances that another app or a security hole will expose the data on the device. Apps may also cache data on the server and thus expose the user through their own site vulnerabilities.
  4. Don't publicly post private data or derivative data - With the wealth of social networks and forums available it is tempting to help the user share exciting and interesting data on places like Twitter, Facebook, and blogs. Don't post user private data to public places without very specific and conscious consent. Even sharing conclusions from the private data such as "John has credit to reloan!" may be more than the user expects to share and is certainly a private account detail not available to others on Kiva.org.
  5. Always require user consent to modify or access private data - Whether your app is making a loan or simply displaying an account balance on the screen, the result can be upsetting for a user if he didn't expect the result. Your application should take a specific action only after confirming user consent. This may be indicated by a button, a dialog, or well-defined gesture. The more sensitive or destructive the action, the more difficult the action should be. For example, a clickable item called "View my Account" might be a reasonable action for retrieving and revealing account details to the user. By contrast making a loan should require multiple deliberate actions such as dragging an item to a basket, clicking "Checkout," and then reviewing and confirming the transaction before processing the final result.

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.

OAuth and Access Tokens

Requesting Protected Resources with an Access Token

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.

User Resources

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:

https://api.kivaws.org/v1/my/account

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:

  • id - This is a unique numerical ID that distinguishes the user account from all other accounts. This number never changes.
  • is_public - True if the user has a public Lender Profile. False if the user is Anonymous.
  • first_name - The first name of the user.
  • last_name - The legal last name of the user.
  • lender_id - This is the name the user chooses to display publically. Equivalent to the 'name' property on a Lender object.

Here's an example of a User Account object in JSON

{ "user_accounts":[ { "id":123456, "is_public":true, "first_name":"John", "last_name":"Smith", "lender_id":"john9999", } ] }
Kiva
  • © 2009 - 2017 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.