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

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

Hi there,

A quick update here, custom scopes for DigitalOcean API Tokens is now in beta!

This API token enhancement provides additional flexibility in protecting your cloud resources by letting you select only the necessary scopes.

Please fill out this form if you are interested in participating in the beta..

Custom scopes introduce more specific permissions, like creating Droplets or updating cloud firewalls. Using custom scopes lets you secure your workflows by granting only the permissions the token needs and restricting access to other resources and actions.

Generally, the CRUD scopes map to equivalent actions on the associated kind of resource:

• Create scope lets you create the resource type and perform additive actions within that resource type. For example, database:create lets you create database clusters and create new users or databases within that cluster.

• Read scope lets you view information about a resource by type and also view information that the resource returns. For example, app:read lets you view App Platform apps and their logs.

• Update scope allows you modify a resource type and perform actions that would otherwise modify a resource. For example, droplet:update lets you power a Droplet on or off.

• Delete scope lets you delete a resource by type and perform actions that delete information about the resource type. For example, database:delete lets you delete databases from a database cluster and remove existing users from a database.

Each custom scope correlates to one public API endpoint.

Best,

Bobby