# DigitalOcean OAuth API

[OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) 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](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) meant for web applications running on a server. It also supports the [implicit authorization flow](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2). 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:

| Endpoint | Description |
|---|---|
| [`/authorize`](#authorize) | Request user authorization |
| [`/token`](#token) | Request an authorized access token |
| [`/refresh`](#refresh) | Refresh an access token using a refresh token |
| [`/revoke`](#revoke) | Revoke an access token |

To use the OAuth API, first [register your application](https://cloud.digitalocean.com/account/api/applications/new) 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](https://docs.digitalocean.com/support/im-getting-an-error-when-using-the-digitalocean-oauth-api./index.html.md).

## `/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](https://cloud.digitalocean.com/account/api/applications), 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

| Parameter | Type | Necessity | Description |
|---|---|---|---|
| `client_id` | string | Required | The client ID for your registered OAuth application on DigitalOcean. |
| `redirect_uri` | string | Required | The callback URL where users are sent after authorization. Must match the callback URL you provided during application registration. |
| `response_type` | string | Required | Set to `code` to request an authorization code. Set to `token` to request an OAuth token for implicit authorization. |
| `scope` | string | Optional | See [all token scopes](https://docs.digitalocean.com/reference/api/scopes/index.html.md). |
| `state` | string | Optional | An unguessable random string. Used to protect against request forgery attacks. Recommended. |
| `prompt` | string | Optional | A space-separated list of strings that Defines the behavior of the authorization page as shown to the user when they authorize an OAuth application. See values below. |

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](#token).
  - 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](https://docs.digitalocean.com/reference/api/index.html.md#digitlaocean) 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`:

```shell
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

| Parameter | Type | Necessity | Description |
|---|---|---|---|
| `grant_type` | string | Required | Must be set to `authorization_code` for an access token request. |
| `code` | string | Required | The code received as a response to authorization with the `/authorize` endpoint. |
| `client_id` | string | Required | The client ID for your registered OAuth application on DigitalOcean. |
| `client_secret` | string | Required | The client secret for your registered OAuth application on DigitalOcean. |
| `redirect_uri` | string | Required | Must match the callback URL that you supplied during application registration. |

### Response

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

```json
{
    "access_token": "doo_v1_EXAMPLE4efe8999d0892b6069bc754a78c656f8e843361e1e4d1cd04ac85c381",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "dor_v1_EXAMPLE3104521c47be0b580e9296453ef4y319b02b5513469f0ec72d99af2e2",
    "info": {
        "name": "Sammy the Shark",
        "email":"sammy@digitalocean.com",
        "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](https://docs.digitalocean.com/reference/api/index.html.md#digitlaocean) 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

| Parameter | Type | Necessity | Description |
|---|---|---|---|
| `grant_type` | string | Required | Must be set to `refresh_token` for a token refresh request. |
| `refresh_token` | string | Required | The `refresh_token` that was received with the original access token. |

### Response

The refresh token response is in the same format as the original access token grant. See [the response for `/token`](#access-token-grant).

## 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

| Parameter | Type | Necessity | Description |
|---|---|---|---|
| `token` | string | Required | Must be set to the value of the access token. |

### Response

The response to this request is an empty JSON object.