API Authentication - version 2

Introduction

Version 2 of our API uses key-based access control.

The simplest way of creating a key is to do so using the “Manage admins” area of your account, in much the same way that normal users are managed: API keys can have the same permission levels as normal users. They can also be restricted either by an expiry date or by IP address.

Keys can also be obtained for an account using OAuth2 and the Authorization Code Grant Type. Although this is more complicated, if you are developing another application that will integrate with Simplelists, then this can provide a more seamless user experience. A user can be redirected from your application to Simplelists where the user logs in, who is then returned back to your application along with the required token.

API keys are very powerful and should be treated with the same protection as you would treat passwords.

Using a simple key

Once a key is created, it is used by adding it to a HTTP request in an Authorization header. The header can be added either as HTTP Basic Authentication or as an OAuth2 Bearer token.

HTTP Basic Authentication

When using HTTP Basic Authentication, provide your API key as the basic auth username value. A password does not need to be provided.

Bearer Header

The API key can also be used in its raw unencoded form by adding it to the Authorization header with the Bearer parameter. For example: Authorization: Bearer CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE

Examples

HTTP Basic Authentication

curl https://dev.simplelists.com/api/2/contacts/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:

Bearer Header

curl https://dev.simplelists.com/api/2/contacts/ -H 'Authorization: Bearer CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE'

Using OAuth2 tokens with the Authorization Code Grant Type

The Authorization Code grant type should be used when you are creating a web application that may be deployed on a server that you or the user will not necessarily trust. By using the Authorization Code grant type, the application will have no knowledge of the Simplelists username and password; it will only have knowledge of an API access token.

It is beyond the scope of this document to describe the full authorization process. In short though, the following process is required:

• Submit a client request to the authorization endpoint. You will need a valid client_id in order to do so.
• The authorization endpoint will return a redirect location, which will be the Simplelists URL that the end user should login at.
• Once the user logs in at Simplelists, they will be asked to confirm the scopes that the API client will have access to and then they will be redirected back to the API client’s defined redirect URI along with an authorization code in the URI's query parameters.
• The API client then POSTs the authorization code to the token endpoint, which will return an access token that can be used in standard API calls in the same way as if it had been obtained using the instructions above for a normal key.

You will need the following details to use the Authorization Code grant type:

Authorization endpoint:	https://dev.simplelists.com/api/2/oauth/authorize/
Client ID:	Please obtain from Simplelists Support
Client secret:	Please obtain from Simplelists Support
Token endpoint:	https://dev.simplelists.com/api/2/oauth/token/
Access token location:	Authorization header with Bearer prefix
Request URI:	As per standard API documentation

Refresh Token Grant Type

The Refresh Token grant type is not used on its own, but is instead used to obtain a new access token once the current one has expired. To use the Refresh Token grant type, you will need to submit a Refresh Token that was previously received when using one of the other methods.

You will need the following details to use the Refresh Token grant type:

Token endpoint:	https://dev.simplelists.com/api/2/oauth/refresh/