Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Authenticate the user:

    1. Encode the username and password the end-user submitted in a standard HTTP authenticate header

    2. Send as a GET to

      For details see API usage examples.

  2. If you do not receive a 204 No Content response: stop.

    From this point on you will use your own API key.

  3. Identify the organisation of the user (if all your users are directly under your domain, this will be a constant but coding to look it up is better practice and allows greater flexibility later).

    1. Make a GET request to
    2. There will be an 'id' in the 'organisation' section of the response
    3. There will also be other information there that may be of use to you
      For details see Fetching individual accounts

  4. Next you obtain a session initiator URL using the submitted username* by making a GET request to<id>/account/session?username=USERNAME&

    1. where <id> is the organisation id you obtained in the previous step

    2. and returnURL is an address in your application or site where the user should be sent next after establishing a session.

      For details see Generating authentication tokens for end-users via the API

  5. The response will include a 'sessionInitiatorUrl'. This URL includes a time limited token.

  6. Send the user to the sessionInitiatorUrl returned in the previous step via a 302 redirect.

    1. The user will then be signed in.


The returnUrl must be to your own application or page rather than a resource because the status parameter will be unexpected anywhere else. 


* As well as submitting a username to initiate a session, you can also use email=EMAILADDRESS in step 4 if those are unique for your end-users. For details see Generating authentication tokens for end-users via the API.