You will need to use OAuth2 in order to authenticate with the API. The grant types currently supported are Resource Owner Password and Authorization Code. Both are detailed below. You will also need to use the Refresh Token grant type if you intend to use your access token for more than an hour.
Before you can use the API, you will need API client credentials. Please contact Support to obtain them.
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 requests API using the Bearer scheme.
You will need the following details to use this:
| Token endpoint: | https://www.simplelists.com/api/token.php |
|---|---|
| Grant type: | password |
| Access token location: | Authorization header with Bearer prefix |
| Username: | A valid Simplelists API username (create using Manage Admins in your account) |
| Password: | The password for the username |
| Client ID: | Please obtain from Simplelists Support |
| Client Secret: | Please obtain from Simplelists Support |
| Request URI: | https://www.simplelists.com/api/api.php |
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. With this approach, 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 |
| Grant Type: | authorization_code |
| 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 |
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://www.simplelists.com/api/token.php |
|---|---|
| Client credentials username: | Please obtain from Simplelists Support |
| Client credentials password: | The password for the client credentials username |
