API Authentication - version 2

Introduction

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

The simplest way of creating an API key is through the Manage Admins area of your account, in much the same way that regular users are managed. API keys can be assigned the same permission levels as regular users. They can also be restricted by expiry date or IP address.

API keys can also be obtained using OAuth2 with either the Authorization Code grant type or the Resource Owner Password grant type. Although this is more complex, it provides a more seamless user experience when developing an application that integrates with Simplelists. Users are redirected from your application to Simplelists to log in and, once authenticated, are redirected back to your application with the required access token.

API keys are very powerful and should be protected in the same way as passwords.

Using a simple key

Once a key is created, it is used by adding it to an 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

Examples

HTTP Basic Authentication

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

Bearer Header

curl https://www.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 this 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:

Resource Owner Password Grant Type

The Resource Owner Password Grant Type allows an application to authenticate on behalf of an API user using the user’s username and password.

With this grant type, the application authenticates using its client credentials and the API user’s username and password. If the request is successful, the API returns an access token and a refresh token. The access token should be included in the Authorization header of all subsequent API requests using the Bearer scheme.

You will need the following details to use this grant type:

 curl -X POST https://www.simplelists.com/api/2/oauth/token/ \
        -d "grant_type=password" \
        -d "client_id"=CLIENT_ID" \
        -d "client_secret=CLIENT_SECRET" \
        -d "username=USERNAME" \
        -d "scope=contact membership list"