Before using Developer API, client must be set up by TripCase administrator.

TripCase administrator must be provided a redirect_uri to set for a given client.

Client is provided with client_id and secret, params that are used in the authentication process.

Authentication

Developer API follows OAuth2 standard to perform authentication.

It is a two step authentication. Access_token is a product of a successful authorization.

It is required as a param (or a header) in any subsequent data calls.

1. Login request:

GET /client_api_permissions?response_type=code&client_id=[client_id]&redirect_uri=[client_app_redirect_uri]

Description

This call is an end point for “Login with TripCase” link. It ends up with one of the following actions, depending on the user’s session in TripCase:

1. TripCase Login page (for a user that is not currently logged-in to TripCase)

2. TripCase Permissions page (for a user that is logged-in to TripCase, but didn’t give the client app permission before)

3. Client Application redirect (for a logged-in user that has given the permissions earlier)

Params

• response_type - required, must be set to 'code'

• client_id - required, must be the same as received from TripCase administrator

• redirect_uri - required, must be exactly the same as given to TripCase administrator

Response

• HTTP 302 - Location header containing redirect_uri with authorization_code set for client browser to follow

• HTTP 404 - For incorrect client_id or redirect_uri not matching URL given to TripCase administator.

2. Token Exchange request:

POST /developer_api/tokens
grant_type=authorization_code&code=[authorization_code]&client_id=[client_id]&client_secret=[secret]&redirect_uri=[redirect_uri]

Description

This call is back end, it serves exchanging authorization_code (received in 1. Login request) for access_token.

Params (x-www-form-urlencoded format)

• client_id - required, as received from TripCase administrator

• client_secret - required, as received from TripCase administrator

• code - required, authorization_code as received from 1. Login request

• grant_type - required, must be set to 'authorization_code'

• redirect_uri - required, must be exactly the same as given to TripCase administrator

Response

HTTP 200, JSON serialized object, containing authentication details and basic user data.

• access_token - access_token for current session, required in all data calls

• expires_in - number of seconds the access_token hash is valid

• refresh_token - token requried to get fresh access_token (see 3. Token Refresh)

• first_name, last_name, primary_email, emails - logged-in user data

Example response

HTTP 200

{"access_token": "4dc258f4a940901195f92256ea14385b8c017c75de0af9cefd28ecbd831502ae",
"token_type"   : "bearer",
"expires_in"   : 7200,
"refresh_token": "b0b5dd6eeafeb98a83f59c86cd3b5d8cbc147f42b09a32e4d821fb2e611ad62a",
"scope"        : "",
"first_name"   : "John",
"last_name"    : "Doe",
"primary_email": "john.doe@example.com",
"emails"       : ["john.doe@localhost", "john.doe@example.com"]}

3. Token Refresh request:

POST /developer_api/tokens
grant_type=refresh_token&client_id=[client_id]&client_secret=[secret]&refresh_token=[refresh_token]

Description

This call is back end, it serves refreshing access_token before it expires.

Params

• grant_type - required, must be set to 'refresh_token'

• client_id - required, as received from TripCase administrator

• client_secret - required, as received from TripCase administrator

• refresh_token - required, received from 2. Token Exchange request

Example response

same as for 2. Token Exchange request

Common params for data calls

All data calls require access_token. It can be passed either as a GET parameter (access_token) or via a HTTP header HTTP_AUTHORIZATION.