For third party agent apps

If you are a broker dealer, RIA, or other type of authorized third party agent, and want to provide investment services on behalf of others, use this flow.

Note: You must be a registered third party agent to create a third party investment client. If you are choosing this option, please contact the Prosper capital markets team at [email protected] to apply for this type of Prosper account prior to registering your app. We must set your Prosper account to a third party agent account. You can then go to Step 1 below to register your app.

The Prosper implementation of security for third party investment clients is an extension of the OAuth 2.0 security protocol. Third party investment clients must use an authorization key security flow to retrieve an authorization key that can be used to generate access/refresh tokens for API calls to the Prosper user’s account. The authorization key is a unique ID that represents the client plus the Prosper user who granted access to the client. In this way, Prosper users can grant access to their account information to your client without having to expose their login credentials directly to you.

Step 1: Register your app with Prosper

If you have not already done so, register your app with Prosper. When your app is registered, you will receive a Client ID and Client Secret, which you will use to authorize your app with Prosper before making API calls.

App registration is done on your Prosper API settings page.

To open the API settings page:

1. Select Settings from your account menu.
2. Select Edit from the API settings section on the right side of the page.

To register your app and receive a Client ID and Client Secret, complete the registration form. Complete all fields.

As part of the app registration process, you are asked to provide a Redirect URL. To prevent fraudulent transactions during the authentication process, we will only communicate with a URL you have registered as a trusted endpoint. Make sure the server hosting your redirect callback URL is listening to complete the authentication workflow for an authorization key.

A well-formed redirect URL:

• should utilize https
• contains no arguments – arguments will be ignored
  https://mycallbackurl.com/authendpoint/callback/?interaction=1 is the same as https://mycallbackurl.com/authendpoint/callback/
• is absolute
  “https://mycallbackurl.com/authendpoint/callback”  is OK, “/authendpoint/callback” is not OK
• cannot include anchors (#’s) https://mycallbackurl.com/authendpoint/callback#prosper will not work

Step 2: Request an Authorization key

Once your app is registered with Prosper with a valid redirect URL, you must direct the user’s browser to Prosper’s OAuth 2.0 endpoint for authorization. Once the request is made, one of the following will happen:

• If the user has not previously granted permission to access their Prosper account, or the grant has been manually revoked by the user, the browser will be redirected to Prosper’s grant access screen. When the user completes the grant access process, the browser is redirected to the redirect URL you provided during the app registration process.

• If there is already a valid access permission grant from the user, the Prosper grant access screen is by-passed and the user is immediately redirected to the redirect URL you provided during the app registration process.

The response to the request is an authorization key that identifies the Prosper user when making a request for an access token. Once you have an authorization key for your user, you do not have to make a new request for an authorization key: the key never expires. Store this authorization key in a safe place.

Note: If you already have an authorization key for the user and make a subsequent request, a new authorization key will be generated.

To request an authorization key:

To make an authorization key request, you will direct the user’s browser to the Prosper authorization endpoint, passing your client id.

Additionally, you should pass a state parameter in the call. The state parameter is simply a pass-through parameter that you can construct for context about the user. Prosper will do no processing of the state value. It will be passed back to your client as part of the redirect response.

Note: You should create a non-guessable state parameter to prevent Cross Site Request Forgery (CSRF) attacks. By doing this, you can ensure the auth key obtained from Prosper is in response to your request rather than some other app.

Making the call

https://www.prosper.com/oauth?client_id=<client_id>&response_type=auth_key&state=<client_state>

The Prosper Grant Access screen will appear in the user’s browser window. After making a selection and granting access, the user will be redirected to the redirect URL you provided when you registered your app. The response will contain the authorization key, any state parameter value you passed in the call, and a list of permission scope values that are tied to the authorization key. Scope values are determined by the permission grant type the Prosper user gave to your client.

Note: You do not need to pass the scope to Prosper when asking for Auth tokens later. The scope is sent to allow you to present client functionality to users that matches the permission they granted to your client (Read/Write or Read-Only).

Examples:

Response to an authorization key request with “Read/Write” scope permissions assigned to the key:

<your_client_redirect_url>?auth_key=<authorization_key>&state=myClientState&scope=write_invest_order%20read_listing%20read_loan%20read_note%20read_prosper_account%20write_user_profile

Response to an authorization key request with “Read only” scope permissions assigned to the key:

<your_client_redirect_url>?auth_key=<authorization_key>&state=myClientState&scope=read_invest_order%20read_listing%20read_loan%20read_note%20read_prosper_account%20read_user_profile

Response to an authorization key request where the user clicked the Cancel button instead of Grant Access. In this case, no scope permissions will be passed to the redirect URL. You will receive an error code of “userCancellation”:

<your_client_redirect_url>?error_code=userCancellation&state=myClientState

Scope parameters

Step 3: Request an access/refresh token

Now that you have an authorization key, you will authorize your app using the OAuth 2.0 Authorization Key flow. This flow results in Prosper issuing an access token for making API calls. You will also receive a refresh token.

Make note of the expiration time for the access token. When the access token has expired, you’ll need to get a new one before you can make calls to the Prosper APIs.

Both the access and refresh tokens have an expiration time. Once the access token has expired, you will use the refresh token to gain a new access token (see next section).

Once the refresh token has expired, you must make a request for a new access/refresh token for client sessions.

To make a token request:
You will make an HTTP urlencoded POST request to Prosper’s OAuth security token endpoint, passing the following parameters:

Request:

POST https://api.prosper.com/v1/security/oauth/token
   Accept: application/json
   Content-type: application/x-www-form-urlencoded

grant_type=authorization_key&client_id=<your_client_id>&client_secret=<your_client_secret>&auth_key=<authorization_key>

View curl and python examples of the above request at the end of this section.

Response:

{
   "access_token": "22a5aaaf-bb7b-4278",
   "token_type": "bearer",
   "refresh_token": "7fcb8a8a-e7dd-4fa9",
   "expires_in": 3599
}

The following parameters are passed back in the response:

Now that you have a user access token, you can make Prosper API calls to inspect resources. Use the access token as bearer in every Authorization request header.

Step 4: Request a new access token

Make note of the expiration time for the access token. When the access token has expired, you’ll need to get a new one before you can make calls to the Prosper APIs.

Note: If your refresh token has expired, you should repeat Step 3 above to retrieve a new access and refresh token.

To make a request for a new access token:

You will make an HTTP urlencoded POST request to Prosper’s OAuth security token endpoint, passing the following parameters:

Request:

POST https://api.prosper.com/v1/security/oauth/token
   Accept: application/json
   Content-type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=<your_client_id>&client_secret=<your_client_secret>&refresh_token=<existing_refresh_token_from_user_token_request>

View curl and python examples of the above request at the end of this section.

Response:

{
   "access_token": "5098afd7-f216",
   "token_type": "bearer",
   "refresh_token": "7fcb8a8a-e7dd",
   "expires_in": 3599
}

The following parameters are passed back in the response:

Errors

Authorization Key Flow Errors

Authorization READ Key Flow Errors

Refresh Token Errors

Client Authority Errors

Authorization key flow token requests: curl and python examples

curl authorization key flow access token request

curl -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=authorization_key&client_id=<your_client_id>&client_secret=<your_client_secret>&auth_key=<your_authorization_key>' 'https://api.prosper.com/v1/security/oauth/token'

curl refresh token request

curl -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=refresh_token&client_id=<your_client_id>&client_secret=<your_client_secret>&refresh_token=<existing_refresh_token_from_user_token_request>' 'https://api.prosper.com/v1/security/oauth/token'

python authorization key flow access token request

import requests
url = "https://api.prosper.com/v1/security/oauth/token"
payload = "grant_type=authorization_key&client_id=<your_client_id>&client_secret=<your_client_secret>
&auth_key=<your_authorization_key>"
headers = { 'accept': "application/json", 'content-type': "application/x-www-form-urlencoded" }
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)

python refresh token request

import requests
url = "https://api.prosper.com/v1/security/oauth/token"
payload = "grant_type=refresh_token&client_id=<your_client_id>&client_secret=<your_client_token>&refresh_token=<existing_refresh_token_from_user_token_request>"
headers = { 'accept': "application/json", 'content-type': "application/x-www-form-urlencoded" }
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)