Authentication and Authorization

Moves uses OAuth 2.0 for authentication and authorization.
In order to access user data via the Moves API, user has to first authorize your application using the Moves app. After authorizing the application, she will be redirected to a callback url with an authorization code.
The authorization code needs to be exchanged for an access token using an authenticated server-side call. You can then use the access token to make Moves API calls.

Authorization with Moves app

Users need to have Moves version 1.5 or later installed on their phones. 1.5 for iPhone was released on June 4th, 2013 in the App Store and 1.5 for Android was released on November 26th, 2013 in the Google Play Store.

Contents

Authorization
Exchanging access token
Refreshing access token
Validating access token
Scopes

Requesting authorization

Mobile website / app

To request authorization from a mobile website or app, direct the user to the following url. This will open the Moves app in the phone and show the authorization request to the user.
The redirect_uri must be provided, so the user can be redirected back to your application in all error cases.

moves://app/authorize?client_id=<your client id>&redirect_uri=<redirect_uri>&scope=<scope>

The url can include the following query parameters:

  • client_id (mandatory): the Client ID your received when registering your application
  • redirect_uri (mandatory): the uri must match one of the callback uris registered for your app, but you may include additional query parameters in the uri.
  • scope (mandatory): requested scopes (space-delimited). Should contain either activity, location or both scopes.
  • state (optional): the state parameter is echoed back and included in the callback uri
Android

Mobile apps on Android can use an intent to ensure smooth authorization flow. See example code at: https://github.com/movesapp/moves-api-android

Website (desktop browser)

To request authorization from a desktop website, direct the user to the following url. This will generate a code that the user is prompted to enter into the Moves app in order to authorize your application.

https://api.moves-app.com/oauth/v1/authorize?response_type=code&client_id=<client_id>&scope=<scope>

The url can include the following query parameters:

  • response_type (mandatory): must be code
  • client_id (mandatory): the Client ID your received when registering your application
  • redirect_uri (optional): the uri must match one of the callback uris registered for your app, but you may include additional query parameters in the uri. If omitted, the default callback uri is used. You can define the default redirect uri in your app info’s development tab.
  • scope (mandatory): requested scopes (space-delimited). Should contain either activity, location or both scopes.
  • state (optional): the state parameter is echoed back and included in the callback uri

Receiving authorization code

If user authorizes your application, she will be redirected to the callback uri with authorization code:

<redirect_uri>?code=<authorizationcode>

The response has the following query parameters:

  • code (mandatory): the authorization code that can be exchanged for access token
  • state (optional): echoed back from the request
Errors

If the authorization is denied or fails, the redirect uri instead includes the error code:

<redirect_uri>?error=<errorcode>
  • error: error code why the authorization did not succeed

Error codes:

  • access_denied: user denied access for your application
  • unauthorized_client: your application is either disabled or the client_id was wrong
  • invalid_request: a parameter is missing or was invalid. For example check that the redirect_uri is valid if you provided one
  • invalid_scope: the scope in request is not a valid scope
  • server_error: there was an unexpected error and the authorization request could not be handled

Exchanging authorization code for access token

The access token request must be done using a server-side call, as it requires the client secret.

Requesting access token

To exchange authorization code for an access token, make a POST request to the access token url endpoint:

https://api.moves-app.com/oauth/v1/access_token?grant_type=authorization_code&code=<code>&client_id=<client_id>&client_secret=<client_secret>&redirect_uri=<redirect_uri>

Parameters:

  • grant_type (mandatory): must be authorization_code
  • code (mandatory): the authorization code you received with the redirect callback from Moves app
  • client_id (mandatory): the Client ID your received when registering your application
  • client_secret (mandatory): the Client Secret your received when registering your application
  • redirect_uri (mandatory/optional): mandatory if the authorization request included the redirect_uri parameter, in which case the value must be identical

Receiving an access token

If the access token request succeeds, the access token is included with the JSON response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"access_token": "1j0v33o6c5b34cVPqIiB_M2LYb_iM5S9Vcy7Rx7jA2630pK7HIjEXvJoiE8V5rRF",
"token_type": "bearer",
"expires_in": 5183999,
"refresh_token": "A27CSzZXKf2EPB45lvLQyT56sZ80dXNtp_lA7lvZ6UIKAy94GNvW9g9aGmJtbl28",
"user_id": 23138311640030064
}
  • access_token: a valid access token to use Moves API
  • token_type: only “bearer” type tokens are used
  • expires_in: the access token lifetime in seconds
  • refresh_token: used to refresh an access token via refresh token call
  • user_id: a unique identifier (64 bit unsigned) of the user associated with the access token
Errors

In case of an error or invalid parameters, an error response is returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8    
{"error": "<errorcode>"}
  • error: error code why the authorization did not succeed

Error codes:

  • invalid_client: the client authentication failed, check that client id and client secret are correct.
  • invalid_grant: the provided authorization code is not valid, has been revoked or has expired (after 5 minutes). Note that both successful and unsuccessful requests revoke the code. Also check that the redirect_uri parameter is included if necessary.
  • invalid_request: the request was malformed. Check that all the required parameters are provided.

Refreshing an access token

The refresh token request must be done using a server-side call, as it requires the client secret.

Refresh token request

Make a POST request to the access token url endpoint:

https://api.moves-app.com/oauth/v1/access_token?grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>

Parameters:

  • grant_type (mandatory): must be refresh_token
  • refresh_token (mandatory): the refresh token issued for the client
  • client_id (mandatory): the Client ID your received when registering your application
  • client_secret (mandatory): the Client Secret your received when registering your application
  • scope (optional): can be used to reduce scopes from the original granted scopes. If omitted the original scopes are used.
Refresh token response

If the refresh token request succeeds, the old access token and refresh token is revoked and new ones are issued.

See “Receiving an access token” above.

Validating an access token

Make a GET request to the token info url endpoint:

https://api.moves-app.com/oauth/v1/tokeninfo?access_token=<access_token>

Required parameters:

  • access_token: an access token

If the access token is valid and has not expired or been revoke, a JSON response is returned:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"client_id": "4j_HGYX1K166lC7Q83m5w0MYXYl45Aj6",
"scope": "activity",
"expires_in": 4468335,
"user_id": 23138311640030064
}
  • client_id: client ID the access token was issued for
  • scope: scopes authorized
  • expires_in: time in seconds until expiry of the access token
  • user_id: a unique identifier (64 bit unsigned) of the user associated with the access token.
Errors

In case the token is not valid, an error response is returned:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8    
{"error": "<errorcode>"}
  • error: error code why the request failed

Error codes:
* invalid_client: the client id associated with token is no longer valid
* invalid_request: the request was malformed
* invalid_token: the token is not a valid token

Scopes

Note that an authorization request with just the default scope is not allowed. You must specify one or more of the explicit scopes.

  • default: implicit scope which is always granted even if not specified in request. Grants access to the user profile API.
  • activity: grants access to the activities APIs (and required for storyline APIs)
  • location: grants access to the places APIs (and required for storyline APIs)