OAuth

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 supports two OAuth 2 grant flows:

The Authorization Code flow for browser-based integrations that can receive a redirect.
The Device Authorization Grant flow for CLIs, CI environments, SSH sessions, and other input-constrained clients that cannot easily open a browser or receive a redirect.

Both flows issue standard Bearer access tokens and refresh tokens. Once issued, the resulting tokens are interchangeable and API requests authenticate the same way regardless of which flow created them.

The device authorization grant must be enabled on each OAuth App from the app’s settings page. The Authorization Code grant is enabled by default, provided the app is configured with a redirect URI.

Errors are handled as specified by the OAuth 2 spec.

Authorize

To initiate the OAuth flow, your application should link to the authorize The Authorize endpoint starts the Authorization Code grant flow. To initiate this 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.
`code_challenge`	No	A PKCE code challenge derived from a verifier you keep secret on the client. Recommended for public clients.
`code_challenge_method`	Conditional	The PKCE transformation used to produce the challenge. Required whenever `code_challenge` is sent. Either `S256` (recommended) or `plain`.

For manual testing during development, you can use the special redirect URI urn:ietf:wg:oauth:2.0:oob. After approval, the authorization code is displayed in the browser instead of being sent to a redirect URI, which is useful when running a CLI or curl-based test.

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.

If you sent a code_challenge in the authorization request, you must include the matching code_verifier when exchanging the code for an access token.

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

Device Code

This endpoint starts the device authorization grant flow. It returns a device_code that your client uses to poll for an access token, and a user_code that the user enters in their browser to authorize the request.

Your OAuth App must have the device authorization grant enabled to use this endpoint. If it is not enabled, the request fails with invalid_client.

Parameters

Parameter	Required	Description
`client_id`	Yes	Your OAuth App’s client ID

Response

If the request succeeds, you will receive a JSON response containing the device code and the information needed to prompt the user to authorize the request.

Attribute	Description
`device_code`	The device verification code, used by the client to poll the token endpoint.
`user_code`	The short, human-readable code that the user enters in their browser.
`verification_uri`	The URL where the user enters the `user_code` to authorize the request.
`verification_uri_complete`	The verification URL with the `user_code` pre-filled. Display this as a QR code or clickable link when possible.
`expires_in`	An integer representing the number of seconds before the `device_code` and `user_code` expire.
`interval`	The minimum number of seconds that the client should wait between polls to the token endpoint.

Prompting the User

After receiving a device code response, direct the user to the verification URL to authorize the request. There are two URLs in the response:

verification_uri_complete is the preferred URL to present to the user. It pre-fills the user_code, so the user only needs to sign in and approve. Render it as a clickable link or QR code when possible.
verification_uri is the fallback for clients that cannot present a clickable link, such as terminals on systems without a URL launcher. Display it alongside the user_code so the user can open the URL and type the code manually.

Always display the user_code to the user as well, so they can confirm the code on the consent screen matches what your client showed them. This protects against a malicious device tricking the user into approving a different request.

While the user authorizes the request, your client polls the Access Token endpoint to obtain an access token.

Example JSON response:

{
  "device_code": "example-device-code",
  "user_code": "ABCD-WXYZ",
  "verification_uri": "https://app.emailable.com/oauth/device",
  "verification_uri_complete": "https://app.emailable.com/oauth/device?user_code=ABCD-WXYZ",
  "expires_in": 900,
  "interval": 5
}

Access Token

This endpoint exchanges an authorization grant for an access token and refresh token. The same endpoint serves both flows; the request differs only in the grant_type value and the grant credential you pass.

Authorization Code Grant

Use this exchange after a successful Authorize request. The authorization code is single-use and expires 10 minutes after it is issued.

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
`code_verifier`	Conditional	The PKCE verifier. Required if a `code_challenge` was sent in the authorization request.

Device Authorization Grant

Use this exchange when polling for a Device Code issued for the device authorization flow. Send only the parameters listed below. Device authorization grant token requests do not use a client_secret, even when the OAuth App also has one for authorization-code requests.

Your client should poll no faster than the interval returned by the Device Code endpoint.

Parameter	Required	Description
`grant_type`	Yes	The string `urn:ietf:params:oauth:grant-type:device_code`
`device_code`	Yes	The device code returned by the Device Code endpoint
`client_id`	Yes	Your OAuth App’s client ID

While the user has not yet approved or denied the request, the endpoint returns OAuth errors that your client should expect and handle as part of the polling loop. See Errors for the full list and the action to take for each.

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.

Tokens issued by the two grants are interchangeable. The response shape is the same regardless of which grant_type you used.

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.

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"

Example JSON response:

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

Refresh Token

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

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.

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"

Example JSON response:

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

Revoke

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

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.

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"

Example JSON response:

Errors

OAuth error responses depend on the endpoint. The token endpoint, including Access Token and Refresh Token requests, the Device Code endpoint, and the Revoke endpoint return JSON with error and error_description fields, as specified by the OAuth 2 and Device Authorization Grant RFCs.

The Authorize endpoint is browser-facing. If a request is invalid before a user can approve it, Emailable renders an error page with a description. If the user denies a valid authorization code request, Emailable redirects back to the registered redirect URI with an OAuth access_denied error response.

Error	Applies to	Description
`invalid_request`	Both	The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
`invalid_redirect_uri`	Authorization code	The supplied redirect URI is malformed or doesn’t match the redirect URI registered for the client.
`invalid_client`	Both	Client authentication failed, the client is unknown, or the requested grant flow is not enabled for the client.
`invalid_grant`	Both	The provided authorization grant is invalid, expired, revoked, does not match the redirect URI, or was issued to another client.
`invalid_scope`	Both	The requested scope is invalid, unknown, or malformed.
`unauthorized_client`	Both	The client is not authorized to use the requested grant type.
`unsupported_grant_type`	Both	The grant type is not supported by the authorization server.
`access_denied`	Both	The user denied the authorization request. For the device flow, stop polling.
`authorization_pending`	Device authorization	The user has not yet approved or denied the request. Continue polling at the current interval.
`slow_down`	Device authorization	Your client is polling too quickly. Increase your polling interval by 5 seconds and continue polling.
`expired_token`	Device authorization	The `device_code` has expired before the user approved the request. Stop polling and request a new device code.

OAuth

Overview

Authorize

Endpoint

Parameters

Response

Device Code

Parameters

Response

Prompting the User

Access Token

Authorization Code Grant

Device Authorization Grant

Response

Refresh Token

Parameters

Response

Revoke

Parameters

Response

Errors

Was this page helpful?

What went wrong?

Recently viewed

General help & guides

Need further help?

On this page

Overview

Authorize

Endpoint

Parameters

Response

Device Code

Parameters

Response

Prompting the User

Access Token

Authorization Code Grant

Device Authorization Grant

Response

Refresh Token

Parameters

Response

Revoke

Parameters

Response

Errors

Was this page helpful?

What went wrong?

Recently viewed