DigitalOcean OAuth API

OAuth 2.0 is an open standard for authorization that enables third-party applications to obtain limited access to a service. The DigitalOcean OAuth API lets you obtain limited access to DigitalOcean teams by delegating authentication to DigitalOcean.

About the DigitalOcean OAuth API

Our OAuth API supports the authorization code flow meant for web applications running on a server. It also supports the implicit authorization flow. This is useful for client-side applications such as mobile or desktop clients where the client secret should not be stored on the user’s device.

The DigitalOcean authorization server, https://cloud.digitalocean.com/v1/oauth, has the following endpoints:

To use the OAuth API, first register your application to use OAuth. Registering an application assigns it a client ID and client secret which you then use in API calls to the DigitalOcean authorization server.

For issues and errors, use the OAuth API troubleshooting guide.

/authorize: Request User Authorization

Use the https://cloud.digitalocean.com/v1/oauth/authorize endpoint as an authorization link to send to a user for your registered OAuth application.

Example

You can view an example link for a registered OAuth application in the control panel. On the OAuth Applications page, click the … next to the application’s name, then click View to open the Oauth Application Details window. In this window, the Link to authorization code section has an example link.

Parameters

The response_type parameter can have the following values:

• code: Requests an authorization code. Used for the authorization code flow for web applications.

  When you use this response type, you request the access token grant with the /token endpoint.

• token: Requests an OAuth token. Used for the implicit authorization flow for client-side applications.

  When you use this response type, you receive the access token grant in a callback.

The prompt parameter can have the following values:

• select_account (default):

  • If a user is not signed in, they are required to sign in.

  • Signed-in users must authorize the OAuth application before proceeding.

• none:

  • Signed-in users who have already authorized the application are redirected back to the valid redirect_url with a new token. A hint can be used by specifying an i query parameter with the first 6 characters of an expected account UUID.

  • Signed-in users who haven’t authorized the application are redirected with error=consent_required. Signed-out users are redirected with error=login_required.

Returns

If the user authorizes the application, DigitalOcean redirects back to your redirect_uri with the following parameters:

• One of the following, depending on the specified response_type:

  • The code parameter with an authorization code. Use this in access token requests to the /token endpoint.

  • The token parameter with an OAuth token. Here is an example callback (access token grant) for token response types:

  https://example.com/callback#access_token=doo_v1_EXAMPLE4ea...381
    &token_type=bearer
    &expires_in=2592000
    &state=0807edf7d85e5d

• The state parameter, if you specified one in the authorization request.

  Verify that the value of state in the response matches the one you provided in the request. If not, it indicates that the request may be a forgery attack created by a third party, and you should abort the request.

• The expires_in parameter, which indicates the time remaining before the token expires in seconds.

The token is available to use to make requests via the DigitalOcean API until the token expires (30 days after being issues) or is otherwise invalidated (for example, revoked or refreshed).

POST /token: Request Authorized Access Token

If a user authorizes your application with the authorization code flow, make a POST request to the https://cloud.digitalocean.com/v1/oauth/token endpoint with the appropriate parameters to request the access token.

Example

Here is an example access token request using curl:

curl -X POST "https://cloud.digitalocean.com/v1/oauth/token?grant_type=authorization_code
  &code=f252c4bd6b1b4d249b7
  &client_id=4c413ac36ac22268
  &client_secret=b05a2ad77b24f3
  &redirect_uri=https://example.com/callback"

Parameters

Response

If the request was successful, the authorization server returns a JSON access token grant similar to the following:

{
    "access_token": "doo_v1_EXAMPLE4efe8999d0892b6069bc754a78c656f8e843361e1e4d1cd04ac85c381",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "dor_v1_EXAMPLE3104521c47be0b580e9296453ef4y319b02b5513469f0ec72d99af2e2",
    "info": {
        "name": "Sammy the Shark",
        "email":"[email protected]",
        "uuid":"EXAMPLE0-a636-11ec-9e9d-3381ceabe039",
        "team_uuid": "EXAMPLE1-a636-11ec-a6ac-1323bf96ef4d",
        "team_name": "My Team"
    }
}

In addition to other information, the response includes two important items: access_token and refresh_token.

The access token is available to use to make requests via the DigitalOcean API until the token expires or token is otherwise invalidated.

POST /refresh: Refresh Token

Each access token comes with a refresh token. You can use a refresh token exactly once to create a new access token (and refresh token). Doing so invalidates the access token that the refresh token was issued with. A common use case is refreshing an expired token.

To refresh a token, make a POST request to the https://cloud.digitalocean.com/v1/oauth/refresh endpoint with the appropriate parameters.

Parameters

Response

The refresh token response is in the same format as the original access token grant. See the response for /token.

POST /revoke: Revoke Token Flow

Revoking an access token invalidates it so that it cannot be used.

To revoke an access token, send a POST request to the https://cloud/digitalocean.com/v1/oauth/revoke endpoint with an Authorization: Bearer header and the appropriate parameters.

Parameters

Response

The response to this request is an empty JSON object.