The ChangeTip API requires authentication, which can be provided via an access token. For application developers, we also provide OAuth2 Access, so your users can login using ChangeTip and give your application approval to carry out actions on the user's behalf.

Create an Application

Register an application with us to gain access to the ChangeTip API endpoints.

You will receive an access token which you can use to access your own data as well as any user's data that your application has been given permission to access.

Once you have an access token, you may append it to the url as a query string parameter named access_token:


    $ curl https://api.changetip.com/v2/currencies/?access_token=<your_access_token>

or send it in an authentication header:


    $ curl -H "Authorization: Bearer <your_access_token>" https://api.changetip.com/v2/currencies/

ChangeTip API Scopes (Permissions)

Introduction:

The security and privacy of our users is of paramount importance at ChangeTip. We want to ensure that users of any applications developed with our API are informed about what they may be sharing. For that reason, ChangeTip offers a variety of permissions, called scopes, that an application may request access to.

Not all ChangeTip applications require every scope that we offer, and it is a best practice to only request the scopes that your application will actually utilize. The user will be presented with a list of scopes your application is requesting, so keeping it down to only those that your application will use is valuable in ensuring users’ comfort with approving your application.

Requesting only the scopes you need:

To specify the scopes you want to request, simply add a “scope” parameter in the authorization URL with a list of scopes separated by spaces.

For example: &scope=read_user_basic%20read_user_full would be appended to your authorization URL to request only the two read_user scopes.

User scopes vs. Application-only scopes:

In order to protect our users' privacy, some of the scopes in our API apply only to the owner of the application, and not all of its end users. For example, read_all_tips_on_channel is not an endpoint that end users likely need to make requests to. If your application wants to access

The scopes that ChangeTip offers are outlined below. Note that scopes marked in dark red are considered “elevated” scopes, and require ChangeTip’s approval before they’ll work for authorized users of your application. However, in order to allow you to start developing right away, they’ll work on your own user account.

User Scopes Description
Application Only Scopes Description

OAuth2 / Login With ChangeTip

OAuth2 is an authentication standard which allows your application to receive a user's permission to act on their behalf. Using OAuth2, your application will receive an access token, which grants you permissions to perform user approved actions.

Actions include activities such as allowing a user to login to your application with their ChangeTip account, viewing their balance, processing tips for them, automatic withdrawals, etc.

How does it work?

Getting started:

  1. Register an application on ChangeTip. Enter a name for your application, upload a logo (optional), and set your redirect URL.
  2. Assuming you're using one of the many available OAuth libraries, make note of your Client ID and Client Secret, as these will be placed in the settings for that library. At this time, you'll want to enter ChangeTip's Authorization URL (https://www.changetip.com/o/authorize/) and Token URL (https://www.changetip.com/o/token/) in your settings as well.
  3. Using the "Sign In with ChangeTip" button above, link to the ChangeTip authorization endpoint. Your OAuth library will automatically generate this link. When the user clicks on this button on your site, they will be prompted to confirm with ChangeTip that they want to grant your application certain permissions (called scopes).
  4. When the user confirms, your application will receive a temporary code called a "grant". Your OAuth library will exchange this code parameter for an access_token that will let you make API calls on the user's behalf.
  5. If your application will support tipping, you will need to send a request to the /v2/verify-channel-user/ endpoint, and provide ChangeTip with the unique user identifier (e.g. username) of the authenticated user on your site.

Maintaining access to the application:

  1. For security reasons, OAuth tokens expire periodically. Therefore, when you request your access_token, your OAuth client library (or custom code you wrote) should save the refresh_token that comes back with your access_token.
  2. When your access token has expired, you can get a new token by making a POST request to /o/token/ with the refresh_token parameter and the value stored earlier. The POST parameters, then, would look something like: grant_type=refresh_token&client_id={your_client_id}&client_secret={your_client_secret}&refresh_token={your_refresh_token}

The open source library you choose will handle the vast majority of the heavy lifting for you, including generating the authorization URL and exchanging grants and tokens - all you'll need to do is put in the proper settings. However, if you're interested in learning more about the intricacies of OAuth2, we recommend this excellent simplified explanation of OAuth2.

Example App

Here, we walk you through an example oauth2 application, written in python / django.