Authentication

There are two methods for authenticating: personal access tokens for testing and controlling your own account via the API, and OAuth for building integrations where you are operating on behalf of another user.

Personal access tokens

Create a Personal Access Token by navigating to your Developer settings.

Click "Create a token" and give your token a name (it's best to indicate how you plan to use the token). Then, use the Authorization header and the Bearer realm to authenticate your requests with your token:

# Example cURL request
curl -H "Authorization: Bearer pt_secret_XXXXXXXXXXX" https://www.paced.email/api/v1/me

OAuth

We follow the OAuth 2 specification for obtaining credentials. Access tokens are short-lived (2 hours). Refresh access tokens using the long-lived refresh token issued during the authorization flow.

Register your application

First, create an OAuth application in your Paced Email developer settings. You'll need to provide the following information:

Name: the name of your application.
Redirect URI: the callback URL to redirect to with a code after the authorization flow (e.g. https://myapp.com/auth/pacedemail/callback)

Once you create your app, you’ll receive a client ID and client secret to use in the OAuth flow.

Requesting access to an account

It's generally a good idea to use an OAuth library to handle this process. There are open source libraries available in most common languages. If you're implementing this flow manually, read on!

To initiate the OAuth flow, send the user to the authorize endpoint and replace <your-client-id> and <your-redirect-uri> respectively:

https://www.paced.email/oauth/authorize?client_id=<your-client-id>&redirect_uri=<your-redirect-uri>&response_type=code

The user will be presented with an OAuth screen like this:

When the user accepts, they'll be redirected to your redirect URI with a code parameter:

https://myapp.com/callback?code=<auth-code>

The auth code in the query string can then be exchanged for an access token. Make a POST request to https://www.paced.email/oauth/token with the following body parameters (form-encoded):

Parameter	Value
`code`	The auth code from the query string.
`client_id`	The client ID from your registered app.
`client_secret`	The client secret from your registered app.
`grant_type`	`authorization_code`
`redirect_uri`	The redirect URI from your registered app.

POST /oauth/token HTTP/1.1
Host: https://www.paced.email
Content-Type: application/x-www-form-urlencoded
Accept: application/json

code=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=authorization_code
&redirect_uri=https://myapp.com/callback

The successful response will have a JSON body with the following properties:

Property	Description
`access_token`	A Bearer token to use in the `Authorization` header of API requests.
`refresh_token`	A refresh token to use to obtain a new access token. You should store this in your database in you need long-term access to the API.
`expires_in`	The number of seconds the `access_token` will remain valid (currently 7200).
`token_type`	`bearer`

To refresh your access token, send a POST request to https://www.paced.email/oauth/token with the following body parameters (form-encoded):

Parameter	Value
`refresh_token`	The refresh token originally issued in the authorization flow.
`grant_type`	`refresh_token`
`client_id`	The client ID from your registered app.
`client_secret`	The client secret from your registered app.

POST /oauth/token HTTP/1.1
Host: https://www.paced.email
Content-Type: application/x-www-form-urlencoded
Accept: application/json

refresh_token=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=refresh_token

The response will be the same shape as the original token response.

Authenticating requests

To authenticate your API requests, include your access token in your Authorization header, prefixed with Bearer:

GET /me HTTP/1.1
Host: https://www.paced.email/api/v1
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxx