Authentication

User accounts

In order to access Agile Planner's API, an end user must have signed up for an account at https://www.agileplannerapp.com.

Once a user has signed up, you (as a third party developer) will be able to use OAuth 2 to access the API, authenticated as the user.

OAuth 2 requires your application to be registered with Agile Planner. See the getting started page; we'll send you a client id and a client secret that you'll need in order to configure OAuth.

Third party libraries

If you're able to use an OAuth 2 library for your language of choice, this would be a good time to have a look at the documentation.

If not don't worry – authenticating with your client id and secret isn't as complicated as you might think. Read on!

Requesting authentication

In the code examples that follow, your client id, secret and callback URL are referred to as CLIENT_ID, CLIENT_SECRET and CALLBACK_URL. Just replace these names with the values for your application when following the guide.

To authenticate a customer against the API you will first need to send them to your application's authorize URL. You can construct it like this:

https://www.agileplannerapp.com.com/oauth/authorize?
  client_id=CLIENT_ID
  &redirect_uri=CALLBACK_URL
  &response_type=code

Note that the callback URL specified for redirect_uri must match the one that your application was registered with (see above).

Send the user to this page as part of your authorization process; they'll be asked whether or not they'd like to authorize your application to access their account.

If the customer authorizes your app their browser will be redirected to the callback URL, with a code parameter in the query string. You'll need this code parameter to obtain an access token.

If the customer denies access to your application, the browser will still be directed back to the callback URL, but the code parameter won't be set. Instead you'll find error and error_description parameters in the query string. The error parameter will be set to access_denied, while the error_description parameter will contain a more friendly description of the problem. Other errors are also possible, but will only occur if some of the parameters are missing or incorrect.

Obtaining an access token

Once the customer authorizes your app, you will need to obtain an access token. You do this by posting some data to the token endpoint URL:

https://www.agileplannerapp.com/oauth/token

The (form encoded) data that you'll need to include in the POST request is:

grant_type=authorization_code
code=ACCESS_CODE
client_id=CLIENT_ID
client_secret=CLIENT_SECRET
redirect_uri=CALLBACK_URL

All the values that you need to substitute are shown in upper case. The ACCESS_CODE parameter is the string that was passed back via the query string of your callback URL, in the code parameter.

If all goes well the HTTP response will contain a JSON object, one of the keys of which will be called access_token.

Parse the JSON and extract the access token.

Making authenticated API requests

The access token is easy to use - when calling any of the API calls documented in this guide, add an HTTP header that specifies the access token:

Authorization: Bearer ACCESS_TOKEN