OAuth Authentication

Every app is issued an App Id and App Secret. These are shown on your app’s store connect page inside your partner account. The app secret should be kept secret; if a third party gets access to it, they’ll be able to impersonate you and get access to any ServiceM8 account that your app is connected with.

There are several steps that an app must complete in sequence to authenticate against an account. At the end of the authentication process, a token is generated that allows the app to make calls to the API on behalf of an account.

If you have not yet registered as a ServiceM8 Developer to receive your App Id and App Secret, read here on how to do so.

Initiating Authentication

To initiate authentication, redirect the user to the following URL:

GET https://www.servicem8.com/oauth/authorize

with the following parameters:

  • response_type (required): OAuth type (eg. “code”)

  • client_id (required): The API key for your app

  • scope (required): The list of required scopes (explained below)

  • redirect_uri (optional): The URL that the user will be sent to once authentication is complete. This URL must be the same host as the Return URL specified in the store connect settings.

Once here, the user will be asked to grant the requested permissions.

Assuming that the user grants access, ServiceM8 redirects them to the redirect_uri specified by the app with a temporary access token code as a parameter. Given the redirect URL:

http://yourapp.com/app

the call will look like this:

GET http://yourapp.com/app?code=TEMP_TOKEN 

Exchanging the Temporary Token

Exchange the temporary token for a permanent access token using the following request:

POST https://www.servicem8.com/oauth/access_token 

with the following parameters:

  • client_id (required): The app id for your app.

  • client_secret (required): The app secret for your app.

  • code (required): The token you received in step 1.

The response will contain your access token.

Using the Permanent Access Token

Use the token to access the API. To do this, include the variable ‘access_token’ on all requests to the API. The token is good for the lifetime of the install, so save it somewhere secure for use later on.

Scopes

Scopes are strings that enable access to particular resources, such as user data. You include a scope in certain authorization requests, which then displays appropriate permissions text in a consent dialog that is presented to a user. Once the user consents to the permissions, ServiceM8 sends your app tokens, which identify the specific authorisation grant. In other words, the scopes and tokens determine what user data the user gives your app permission to access.

 

ServiceM8 supports incremental authorisation. This feature enables your app to request initial permissions at sign-in and additional permissions at a later time, typically just before they are needed. For example, if your app allows users to create jobs, you can ask for basic user information at sign-in, and later ask just for job creation permissions when the user is ready to create their first job. At this point, the consent dialog box asks the user only for the new permissions, which gives them a simpler, in-context decision to make. You might use this technique if you suspect users are not signing in because your consent screen is overwhelming, or are confused as to why they are being asked for certain permissions. This feature can improve your sign-in conversion rate if you configure your initial scopes to be only the minimum that your app requires to get the user started.

 

The following scopes, with user consent, provide access to otherwise restricted user data.

Scope

Description

staff_locations

Access to real-time GPS information about staff

staff_activity

Access to clock on, lunch break and clock off information about staff

publish_sms

Access to send SMS messages to customers and/or staff on your behalf.

Note sending SMS messages will incur account charges.

publish_email

Access to send Email messages to customers and/or staff on your behalf

vendor

Access to basic account information

vendor_logo

Access to account logo

vendor_email

Access to account holder email address

read_locations

Read-only access to Location Endpoint

manage_locations

Full access to Location Endpoint

read_staff

Read-only access to Staff Endpoint

manage_staff

Full access to Staff Endpoint

read_customers

Read-only access to Company Endpoint

manage_customers

Full access to Company Endpoint

read_customer_contacts

Read-only access to CompanyContact Endpoint

manage_customer_contacts

Full access to CompanyContact Endpoint

read_jobs

Read-only access to Job Endpoint

manage_jobs

Full access to Job Endpoint

create_jobs

Ability to create jobs on behalf of account.

Note creating jobs may incur account charges.

read_job_contacts

Read-only access to JobContact Endpoint

manage_job_contacts

Full access to JobContact Endpoint

read_job_materials

Read-only access to JobMaterials Endpoint

manage_job_materials

Full access to JobMaterials Endpoint

read_job_categories

Read-only access to Categories Endpoint

manage_job_categories

Full access to Categories Endpoint

read_job_queues

Read-only access to Job Queues Endpoint

manage_job_queues

Full access to Job Queues Endpoint

read_tasks

Read-only access to Tasks Endpoint

manage_tasks

Full access to Tasks Endpoint

read_schedule

Read-only access to JobActivity Endpoint

manage_schedule

Full access to JobActivity Endpoint

read_inventory

Read-only access to Materials Endpoint

manage_inventory

Full access to Materials Endpoint

read_job_notes

Read-only access to job notes

publish_job_notes

Ability to add new job notes

read_job_photos

Read-only access to job photos

publish_job_photos

Ability to add new job photos

read_job_attachments

Read-only access to existing job attachments, quotes and invoices

publish_job_attachments

Ability to add new file attachments to jobs

read_inbox

Read-only access to inbox messages

read_messages

Read-only access to staff messages

manage_notifications

Ability to read notifications and mark as read

manage_templates

Full-access to email, sms and document templates

manage_badges

Full-access to create/modify job badges

User Impersonation

By default your app will receive the full privileges you have been granted by the user. For some requests it is desirable to POST data as a given account user rather than as your app itself. Eg. If you are a staff messaging app, you would post messages to other staff on behalf of the current user authenticated with your app. User impersonation automatically implements security for a given user, for example querying the jobs endpoint for all jobs as a restricted staff member will result in only records being returned that specific staff member is authorised to view.

To impersonate an account user, you must set the header “x-impersonate-uuid” in your API GET/POST/PUT/DELETE request.  ‘x-impersonate-uuid’ must be an active, valid staff uuid for the current account.

Authentication and Add-on Directory Installs

If your app is installed from the ServiceM8 Addon Directory then the user will be redirected to your default app URL as defined in the app’s store connect settings. You will then have to start the auth process as described above.

Revoking access to a token or application

At any time, a user can revoke access to any connected application by following the “Add-ons authorised to access the account” link from within the Settings Menu.

Date of Last Revision: June 13, 2014