What is the difference between an API Token and a Personal Token?

September 13, 2015 13.6k views
Java API Security
russjr08
By:
russjr08

Hi,

I'm trying to develop an Android DigitalOcean app, and I'm having a hard time with authorization.

Currently, I am using this library to access DigitalOcean's API from Java. Here's what I'm doing in terms of authentication:

  • If no token is stored, open the login activity. ASK (I'm not prompting for specific credentials) the user to authorize the app.
  • Upon clicking the button, a WebView comes up with the URL set to the URL that is given in the Apps & API page for my app.
  • The user then logs into DigitalOcean, and DigitalOcean asks the user if they'd like to allow my app to read their information.
  • User clicks yes, DigitalOcean redirects to callback URL with the token as a parameter. My app is configured to open the URL scheme, and extracts the token.
  • I open up the main activity, the activity gets the token and passes it to the Java wrapper I'm using
  • Finally, I try to grab the available droplets, and get an "Unable to authenticate you" error...

I pulled the token from the app and tried to manually use it in cURL with

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer MyTokenFromAppHere' "https://api.digitalocean.com/v2/droplets?page=1&per_page=1"

I also get the unable to authenticate message. Now when I replace the token with a personal token, I get the expected response (a listing of my droplets).

So my main question is, what's the difference between an OAuth API token, and a personal token? Surely I'm not supposed to ask the user to generate a personal token to plug into the app, right...?

Edit: Also, I tried basic authentication (-u "TokenHere:") and still the same message.

Log In to Comment
1 Answer
asb MOD September 16, 2015

A "Personal Access Token" and one received via the oAuth flow are essentially the same thing just obtained in a different manner. We allow users to generate PATs in the control panel for use in things like scripts and single user applications rather than having to perform the oAuth dance.

How exactly are you requesting the token? There are two approaches to doing so, a server-side one and a client-side (a.k.a. the "implicit" flow). Check out this article for a good introduction to oAuth2.

For the server side flow, the initial request would look like:

https://cloud.digitalocean.com/v1/oauth/authorize?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://example.com/callback
  &scope=read%20write
  &state=RANDOM_STRING

This does not return an oAuth token, It returns an authorization code as part of the call back url. (E.g. https://example.com/callback?code=e2775a296abb3ad44798ab9&state=0807edf7d85e5d). A second request is then necessary to get the token. Like:

curl -X POST "https://cloud.digitalocean.com/v1/oauth/token?grant_type=authorization_code
  &code=AUTH_CODE
  &client_id=CLIENT_ID
  &client_secret=CLIENT_SECRET
  &redirect_uri=https://example.com/callback"

This will return a json object containing the actual token:

{
  "access_token": "547cac21118ae7",
  "token_type": "bearer",
  "expires_in": 2592000,
  "refresh_token": "00a3aae641658d",
  "scope": "read write",
  "info": {
    "name": "Sammy the Shark",
    "email":"sammy@digitalocean.com",
    "uuid":"e028b1b918853eca7fba208a9d7e9d29a6e93c57"
  }
}

This is useful as it also returns some user information and a refresh token. The drawback is that it requires sending your "client secret" which you do not want to have stored on a user's device.

For a phone app, you'll want to use the client side approach. The request would look like:

https://cloud.digitalocean.com/v1/oauth/authorize?response_type=token
     &client_id=CLIENT_ID
     &redirect_uri=https://example.com/callback
     &scope=read%20write

This would return the token in the callback url:

https://example.com/callback#access_token=ACCESS_TOKEN
An Introduction to OAuth 2
by Mitchell Anicas
OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service, such as Facebook, GitHub, and DigitalOcean. It works by delegating user authentication to the service that hosts the user account, and authorizing...
Reply
  • russjr08 September 18, 2015

    Thanks! I was using the server URL by accident. I picked it up from the DigitalOcean API Control Panel, maybe there should be a toggle of some sorts that shows either the client URL or the server URL?

    I noticed there was an expiration field on the returned callback, is there any documentation on the expiration stuff? What unit is the expiration time in? Do I need to ask the user for a new token after the expiration passes?

    • asb MOD September 21, 2015

      If you were using the "server side" workflow, you are given a "refresh token." You would be able to use that to generate a new token without user interaction. By default, the token is valid for 30 days.

Have another answer? Share your knowledge.

Related Questions