Moovila API: Code Example

App Registration Details Screen

After setting up the basics for the App Registration, the Details screen will show all of the information you need from Moovila to initiate authentication and request Authorization Tokens.

Here is a quick summary of the fields used in these processes.

a.	Callback URLs: After the Moovila OAuth Login form is completed and the end user grants authorization to your Client app for access Moovila on their behalf, the form closes and sends an Authorization Code back to the client app. You must specify the URL to which this code will be sent, or a listing of approved URLs, when setting up the App Registration to ensure that Moovila will only send these authorization codes to a URL which you have deemed appropriate.
b.	Authorization URL: This URL is generated by Moovila and is what your Client app will call to initiate authorization and show the Moovila OAuth Login form.
c.	Token URL: This URL is generated by Moovila and is what your Client app will call to request a new Authorization Token or refresh the token before the current one you’re using expires.
d.	Client ID: A unique identifier created for your Client app that is associated with this App Registration.
e.	Client Secret: A unique string to be paired with the Client ID. Treat this like a password and if you feel that it is ever compromised, you have the option to have it refreshed from this screen.

Initiating the Authentication Request

After setting up the App Registration in Moovila, the Client app you are building, or integrating Moovila into, will need to call the Authorization URL (field B in screenshot) with the following parameters:

• client_id : Client ID obtained from the App Registration Details screen (field D in screenshot)
• scope : space-separated listing of selected scopes. See table above for accepted values. For example, if your Client app only needs access to read projects, tasks and lookup tables, then the string value (prior to URL encoding) to be used would be “ProjectTaskRead LookupTablesRead”.
• redirect_url : One of the specified Callback URLs (field A in the screenshot). This will need to be URL encoded.
• response_type : The string value “code”
• response_mode : The string value “query”
• state : A value which you define to also be used for subsequent token request calls, so be sure to use the same value throughout the various requests

As an example, assuming:

• Authorization URL = “https://app.moovila.com/oauth/index.html”
• Callback URL = “https://www.mytestapp.com/oauth/landing”
• Scopes = “ProjectTaskRead LookupTablesRead TimeEntriesRead”
• Client ID = “23456dfghj5678bhjk678fghjvbn”
• State = “mystatevalue”

Then the URL for initiating the authentication process would look like this:

https://app.moovila.com/oauth/index.html?client_id=23456dfghj5678bhjk678fghjvbn&scope= ProjectTaskRead%20LookupTablesRead%20TimeEntriesRead&redirect_uri=https%3A%2F%2Fwww.mytestapp.com%2Foauth%2Flanding&response_type=code&response_mode=query&state=mystatevalue

If successful, the Callback URL will be called by Moovila with the State value sent back along with an Authorization Code value. Your Client app should validate that the State value matches what you had sent to Moovila via the Authorization URL.

Request an Access Token

Now that Moovila has received authorization from the end user to allow your Client app to access Moovila data on their behalf and your Client app has an Authorization Code to represent that permission, this Authorization Code can now be used to request an Access Token from the server-side of your Client App.

Given the following values to the parameters:

• Token URL = “https://api.moovila.com/Security/OAuth/token”
• Callback URL = “https://www.mytestapp.com/oauth/landing”
• Scopes = “ProjectTaskRead LookupTablesRead TimeEntriesRead”
• Client ID = “23456dfghj5678bhjk678fghjvbn”
• Client Secret = “kjs8oce828dsjhf97ryfsdd”
• Authorization Code = “eygd8xchasiq7qwkwcxn”

The URL for the Access Token request would look like:

https://api.moovila.com/Security/OAuth/token?client_id=23456dfghj5678bhjk678fghjvbn&client_secret=kjs8oce828dsjhf97ryfsdd&scope=ProjectTaskRead%20LookupTablesRead%20TimeEntriesRead&code=eygd8xchasiq7qwkwcxn&redirect_uri=https%3A%2F%2Fwww.mytestapp.com%2Foauth%2Flanding&grant_type=authorization_code

Refresh Access Token

Ideally prior to your Access Token expiring, you’ll request a refresh of the Access Token from the server-side of your Client App. This is done through the same Token URL, but using a grant type of “refresh_token” instead of “authorization code” and passing along the Refresh Token that was received alongside the original Access Token.

Given the following values to the parameters:

• Token URL = “https://api.moovila.com/Security/OAuth/token”
• Callback URL = “https://www.mytestapp.com/oauth/landing”
• Client ID = “23456dfghj5678bhjk678fghjvbn”
• Client Secret = “kjs8oce828dsjhf97ryfsdd”
• Refresh Token = “uhkjsdfhorw83ir8jchsdjjcXNi”

The URL for the Access Token request would look like:

https://api.moovila.com/Security/OAuth/token?client_id=23456dfghj5678bhjk678fghjvbn&client_secret=kjs8oce828dsjhf97ryfsdd&redirect_uri=https%3A%2F%2Fwww.mytestapp.com%2Foauth%2Flanding&grant_type=refresh_token&refresh_token=uhkjsdfhorw83ir8jchsdjjcXNi

Authentication for a Moovila API Endpoint Call

Once you have a valid Access Token, then your requests to the API endpoints must include the jwt that is returned from the Token URL calls in the header as the bearer authorization value.

‘Authorization’: ‘Bearer $jwt’

For more information, visit Connecting into Moovila via the App Registration or Creating an App Registration in Moovila.