# OAuth

Authenticate your users with Emailable using OAuth 2.

## Overview

These endpoints are used to authenticate to OAuth Apps you've created in
Emailable. OAuth apps allow you to authenticate your users with Emailable and
make API requests on their behalf.

Emailable implements the OAuth 2
[Authorization Code](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
flow.

Errors are handled as specified by the
[OAuth 2 spec](https://datatracker.ietf.org/doc/html/rfc6749).

## Authorize

To initiate the OAuth flow, your application should link to the authorize
endpoint with the necessary parameters.

If any parameters are incorrect or if a required parameter is missing, the
rendered page will not prompt the user to authorize. Instead, it will display
an error page containing an error description.

### Endpoint

`GET https://app.emailable.com/oauth/authorize`

### Parameters

Parameter       | Required | Description
--------------- | -------- | -----------
`response_type` | Yes      | The string `code`
`client_id`     | Yes      | Your OAuth App's client ID
`redirect_uri`  | Yes      | Your OAuth App's redirect URI
`state`         | No       | An arbitrary string included in the request that the server returns unchanged, allowing the client to verify the response and prevent CSRF.

### Response

If the request succeeds, the user will be redirected to your redirect URI with
an authorization code. You will also receive a state string if you provided
one. The authorization code expires 10 minutes after it is issued.

Attribute   | Description
----------- | -----------
`code`      | The authorization code generated by the server.
`state`     | The state string, if one was provided in the request.

## Access Token

```shell
curl -X POST "https://app.emailable.com/oauth/token" \
-d "grant_type=authorization_code" \
-d "code=example-code" \
-d "client_id=example-client-id" \
-d "client_secret=example-client-secret" \
-d "redirect_uri=https://example.com/oauth/callback"
```

```ruby
# Not supported by the client library. See the curl example.
```

```javascript
// Not supported by the client library. See the curl example.
```

```python
# Not supported by the client library. See the curl example.
```

> Example JSON response:

```json
{
  "access_token": "example-access-token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "example-refresh-token",
  "scope": "all",
  "created_at": 1743861442
}
```

This endpoint is used to request an access token and a refresh token using an
authorization code and your OAuth client credentials.

### Endpoint

`POST https://app.emailable.com/oauth/token`

### Parameters

Parameter       | Required | Description
--------------- | -------- | -----------
`grant_type`    | Yes      | The string `authorization_code`
`code`          | Yes      | The authorization code received from the authorization request
`client_id`     | Yes      | Your OAuth App's client ID
`client_secret` | Yes      | Your OAuth App's client secret
`redirect_uri`  | Yes      | Your OAuth App's redirect URI

### Response

If the request succeeds, you will receive a JSON response containing an access
token and a refresh token. The access token is what you will use to
authenticate requests to the Emailable API, as described in
[Authentication](/docs/api/authentication).

Attribute       | Description
--------------- | -----------
`access_token`  | The access token used to authenticate the user
`refresh_token` | The refresh token that can be used to request new access tokens
`token_type`    | The string `Bearer`
`expires_in`    | An integer representing the number of seconds before the access token expires.
`scope`         | The string `all`. We do not currently implement scopes, so you can disregard this parameter.
`created_at`    | An integer timestamp indicating when the access token was created.

## Refresh Token

```shell
curl -X POST "https://app.emailable.com/oauth/token" \
-d "grant_type=refresh_token" \
-d "refresh_token=example-refresh-token" \
-d "client_id=example-client-id" \
-d "client_secret=example-client-secret"
```

```ruby
# Not supported by the client library. See the curl example.
```

```javascript
// Not supported by the client library. See the curl example.
```

```python
# Not supported by the client library. See the curl example.
```

> Example JSON response:

```json
{
  "access_token": "example-access-token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "example-refresh-token",
  "scope": "all",
  "created_at": 1746745624
}
```

This endpoint is used to request a new access token using a refresh token and
your OAuth client credentials.

### Endpoint

`POST https://app.emailable.com/oauth/token`

### Parameters

Parameter       | Required | Description
--------------- | -------- | -----------
`grant_type`    | Yes      | The string `refresh_token`
`refresh_token` | Yes      | The refresh token issued to the client
`client_id`     | Yes      | Your OAuth App's client ID
`client_secret` | Yes      | Your OAuth App's client secret

### Response

If the request succeeds, you will receive a JSON response containing a new
access token and a new refresh token.

Attribute       | Description
--------------- | -----------
`access_token`  | The access token used to authenticate the user
`refresh_token` | The refresh token that can be used to request new access tokens
`token_type`    | The string `Bearer`
`expires_in`    | An integer representing the number of seconds before the access token expires.
`scope`         | The string `all`. We do not currently implement scopes, so you can disregard this parameter.
`created_at`    | An integer timestamp indicating when the access token was created.

## Revoke

```shell
curl -X POST "https://app.emailable.com/oauth/revoke" \
-d "token=example-access-token" \
-d "client_id=example-client-id" \
-d "client_secret=example-client-secret"
```

```ruby
# Not supported by the client library. See the curl example.
```

```javascript
// Not supported by the client library. See the curl example.
```

```python
# Not supported by the client library. See the curl example.
```

> Example JSON response:

```json
{}
```

You can use this endpoint to revoke an access token, making it so it can no
longer be used to authenticate requests.

### Endpoint

`POST https://app.emailable.com/oauth/revoke`

### Parameters

Parameter       | Required | Description
--------------- | -------- | -----------
`token`         | Yes      | The access token to revoke
`client_id`     | Yes      | Your OAuth App's client ID
`client_secret` | Yes      | Your OAuth App's client secret

### Response

If the request succeeds, you will receive an empty JSON response.