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 flow.
Errors are handled as specified by the OAuth 2 spec.
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
This endpoint is used to request an access token and a refresh token using an authorization code and your OAuth client credentials.
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.
| 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
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. |
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.