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