API Authentication

Introduction

You will need to use OAuth2 in order to authenticate with the API. The grant types currently supported are User Credentials and Authorization Code. Both are detailed below, along with links to example PHP code. You will also need to use the Refresh Token grant type if you intend to use your API session token for more than an hour. Before you can use the API, you will need an API client username and password; please contact Support to obtain one.

User Credentials Grant Type

The User Credentials grant type is the simpler of the 2 grant types. It should be used when you trust the application from which you are making the API calls, as the application will have knowledge of your Simplelists API username and password. If you are making your own bespoke application to interface directly with your Simplelists account, this is probably the choice for you.

You will need the following details to use the User Credentials grant type:

Token endpoint:	https://www.simplelists.com/api/token.php
Access token location:	Authorization header with Bearer prefix
Username:	A valid Simplelists API username (create using the Manage Users option in your account)
Password:	The password for the username
Client credentials username:	Please obtain from Simplelists Support
Client credentials password:	The password for the client credentials username
Request URI:	https://www.simplelists.com/api/api.php

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.

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

Authorization endpoint:	https://www.simplelists.com/api/authorize.php
Token endpoint:	https://www.simplelists.com/api/token.php
Access token location:	Authorization header with Bearer prefix
Client credentials username:	Please obtain from Simplelists Support
Client credentials password:	The password for the client credentials username
Request URI:	https://www.simplelists.com/api/api.php

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 Reresh Token grant type:

Token endpoint:	https://www.simplelists.com/api/token.php
Client credentials username:	Please obtain from Simplelists Support
Client credentials password:	The password for the client credentials username