Authentication & OAuth2

  • Version: 1.0
  • Host: whats.todaysplan.com.au/rest
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json
More Info

Authentication & sessions

Most API calls require a user to be authenticated.

Your application will use an OAuth2 pairing process to obtain a bearer token which can be used to authorize your HTTP requests.

Once you have a bearer token for a user, every HTTP request should have an Authorization header set;

Authorization: Bearer <token>

Additionally, the servers support authenticated sessions. To ensure that your HTTP requests are able to re-use an session, you should honour the Set-Cookie headers when you make requests.

You will get a Set-Cookie with a JSESSIONID, as well as various AWS LB Set-Cookie headers.

Set-Cookie = JSESSIONID=TR4t0yRVTH8esA54fX3-78yi.undefined; Path=/

These should always be honoured by your HTTP client.

OAuth pairing

Before an access token can be requested for a user, the 3rd party developer will need to obtain a unique client_id and client secret from Today’s Plan.

Depending on the type of OAuth access request type being used, the 3rd party developer will also need to provide an authorization code URI redirect target.

ie when an authorization is requested, and the user accepts the access request, an authorization code is returned to the application via a redirect to the 3rd party website.

Once an OAuth access token has been granted for a user, this should be placed into the Authorization Bearer header for all HTTP requests.

Authorization: Bearer <token>

Two grant type (token negotiation) modes are supported;

  • grant_type = password
  • grant_type = code

The password grant type allows for a token to be allocated with a single command - whereby both the user’s Today’s Plan credentials and the app’s client id and client secret are presented in a single command.

The code grant type is a two phase process, and represents the more traditional OAuth token establishment, whereby the app does not ever see the user’s credentials.

We support a range of redirect URI formats including;

  • Simple call back - https://acme.com/tokenexchange/todaysplan
  • Simple call back with query - http://acme.com/oauth.aspx?provider=todaysplan
  • Wildcard - *.acme.com
  • App urls - Acme://oauth/response