In order to access Agile Planner's API, an end user must have signed up for
an account at
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
isn't as complicated as you might think. Read on!
In the code examples that follow, your client id, secret and callback URL are
referred to as
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_description parameters in the query
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:
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
If all goes well the HTTP response will contain a JSON object, one of the keys
of which will be called
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