Authentication

Venmo uses OAuth 2.0 to authenticate its users with your app. All requests to the API require an access token and must be sent to over https. Without an access token, requests to our API will be denied. Be sure to securely store access tokens on your server and keep in mind that access tokens can expire anytime.

Getting your own access token without OAuth

A developer often wants an access token for their own account so they can start interacting with our API before integrating an OAuth flow. An access token for your own account can be found by logging in, going to the developer tab in your settings, and clicking 'Get Token'. This access token has the ability to make payments from your Venmo account and access to your balance, phone number, primary email and profile information, so keep it secure. If you want a new access token, you can expire the old token and generate a new one by clicking 'refresh'.

Getting an access token with OAuth

The first step towards getting an access token is to redirect your user to the authorization URL. Venmo will prompt the user to give your application access to their Venmo account. The user agrees by signing into their Venmo account and will be redirected back to your app.

There are two options for redirecting back to your app:

• Server-Side Flow - Venmo will redirect to your app with a code in the URL. Your app must then make an additional HTTP POST with that code to and your app's credentials to our servers to get the user's access access token. The access token will be valid for 60 days and can be refreshed using the refresh token. Server-side flow is recommended.
• Client-Side Flow - Venmo will redirect to your app with the access token, but it will only last for 30 minutes and cannot be refreshed. This flow is ideal for lighter apps without backends.

Redirecting to Venmo

Redirect your user to the URL

https://api.venmo.com/v1/oauth/authorize?client_id=<client_id>&scope=<scopes>

The following parameters can be set in the URL:

• client_id (required) — You can find your client ID by signing in.
• scope (required) — Scopes should be space delimited. You can find a list of the available scopes below.
• response_type — The response_type can be set either to token or code. Use code if you plan on implementing server-side flow, and token for client-side flow. If you do not pass this parameter, we specify token by default.
• redirect_uri — Specifies where the user is redirected after authentication. This must have the same base URL as the web_redirect_url registered with your Venmo app.
• state — State parameter can be set to anything and will be returned in the redirect url. This is useful for protecting your app against CSRF attacks. More information about CSRF attacks can be found here.

Server Side Flow

For the server side flow you must set response_type=code. After the user authorizes your app with Venmo, we will redirect the user back to your redirect_uri, with a code in the URL parameter.

Example authorization endpoint URL:

https://api.venmo.com/v1/oauth/authorize?client_id=CLIENT_ID&scope=make_payments%20access_profile%20access_email%20access_phone%20access_balance&response_type=code

Example redirect URL returned:

https://myexampleapp.com/oauth?code=AUTHORIZATION_CODE

That code can be exchanged for an access token with a server-side POST request to:

https://api.venmo.com/v1/oauth/access_token

with the following parameters: client_id, code,client_secret. You can find your client_idand client_secret by logging in.

Example request (in Python):

import requests
data = {
  "client_id": CLIENT_ID,
  "client_secret": CLIENT_SECRET,
  "code": AUTHORIZATION_CODE
}
url = "https://api.venmo.com/v1/oauth/access_token"
response = requests.post(url, data)
response_dict = response.json

Server Side Flow Response

response_dict (from the code snippet above) is a dictionary which takes the following form:

{
  "access_token": "ysAy5EpbZmkVxAfkBTN7t3jjnrdwXYfh",
  "balance": 30.73,
  "expires_in": 5184000,
  "token_type": "bearer",
  "user": {
    "username": "delavara",
    "first_name": "Cody",
    "last_name": "De La Vara",
    "display_name": "Cody De La Vara",
    "is_friend": false,
    "friends_count": 165,
    "email": "coolguy12345@gmail.com",
    "phone": "5555555555",
    "about": "So happy",
    "profile_picture_url": "https://venmopics.appspot.com/u/v3/s/6ecc7b37-5c4a-49df-b91e-3552f02dc397",
    "id": "1088551785594880949",
    "date_joined": "2013-02-10T21:58:05"
  },
  "refresh_token": "CHPCgpanAptd2SwqdwV8r8KkCHYCEBsR"
}

Note: if you ask for email, phone or balance scope, we will return the appropriate values.

Refreshing Tokens

Although server-issued tokens expire after ~60 days, they can be refreshed after (and only after) they expire. Refreshing tokens allows your app to persist granted access without forcing the user to reauthorize your app. If you're interested in learning more about how refresh tokens work in OAuth 2.0, we recommend reading the description laid out in the OAuth 2.0 spec.

After your access token has expired, you can refresh your tokens by issuing a request to /access_token with your client_id,client_secret and refresh_token.

import requests
data = {
  "client_id": CLIENT_ID,
  "client_secret": CLIENT_SECRET,
  "code": AUTHORIZATION_CODE
}
url = "https://api.venmo.com/v1/oauth/access_token"
response = requests.post(url, data)
response_dict = response.json

The body of the response will be a JSON encoded dictionary with the following keys: access_token, refresh_token, expires_in.

The old access token and refresh token will be invalid after they've been refreshed so make sure to substitute them in your database with the new values.

Denied Access

If the user denies access to your app, you will get redirected back to your app with an error query parameter describing the error:

https://myexampleapp.com/oauth?error=User+denied+your+application+access+to+his+or+her+protected+resources.

Client Side Flow

The client-side or implicit flow is designed for apps that prefer or are not able to make server side requests. Tokens generated in this way expire after 30 minutes. If you require persistent, unexpiring tokens, you should implement the Server Side flow.

For the client side flow you must set response_type=token. After the user authorizes your app with Venmo, we will redirect the user back to your redirect_uri, with an access_token in the URL parameter.

Example authorization endpoint URL:

https://api.venmo.com/v1/oauth/authorize?client_id=CLIENT_ID&scope=make_payments%20access_profile&response_type=token

Example redirect URL returned:

https://myexampleapp.com/oauth?access_token=ESG7LmTAkzJY4JUNgy3s4q4aq4HuQQF

The token can then be accessed and stored by grabbing the access_token parameter in the redirect URL.

Scopes

We provide different scopes that encapsulate different permissions that users can grant your application.

• make_payments - Can make transactions (payments and requests) on the authenticated user’s behalf, within a user's weekly spending limit.
• access_payment_history - Can see the authenticated user's payment history.
• access_feed - Can see posts on the authenticated user's feed.
• access_profile - Can see the authenticated user's basic profile information.
• access_email - Can see the authenticated user's primary email address.
• access_phone - Can see the authenticated user's phone number.
• access_balance - Can see the authenticated user's balance.
• access_friends - Can see the authenticated user's friend list.