Private Applications (HTTP Basic Auth)

Private applications are designed for use cases where you are connecting to your own ServiceM8 account, or to one specific customer’s account, and do not intend to promote/list your add-on on the ServiceM8 Add-ons Directory or promote it to a wider audience.

Please note that Basic Auth is not supported for accounts using Two Step Authentication (2SA). In order to access the ServiceM8 API for accounts with 2SA enabled, you will need to implement OAuth 2.0 as described below.

Getting Started with a Private Application

  1. Private applications can connect directly to the ServiceM8 API using your ServiceM8 account username (email) and password.
  2. Read up on the REST API for information on how to access and update your data

Public Applications (OAuth 2.0)

Public applications are designed for external apps or add-ons targeted at all ServiceM8 users. Public applications have additional benefits over private applications such as:

  • Potential to be listed in the ServiceM8 Add-ons Directory
  • Can send SMS and Email messages via the ServiceM8 Platform
  • Web-hooks provide real-time data updates
  • Seamless integration with the ServiceM8 Platform UI – including preferences, custom fields, badges and other functionality

Getting Started with a Public Application

  1. Register as a Development Partner
  2. Login to your account, then click the Developer link in the main menu
  3. Click “Add Item” to create your add-on
  4. After you save your add-on, you’ll be issued with an App Id and App Secret
  5. Implement OAuth 2.0 Authentication in order to allow your add-on to access customer’s ServiceM8 accounts


Signing up as a Development Partner, creating a Public Application, and implementing OAuth 2.0 is required in order to take advantage of some ServiceM8 APIs. This does not mean you have to make your add-on publicly available. You can create a Public Application and choose not to list it on the ServiceM8 Add-on Store.

Implementing OAuth 2.0

If you are already familiar with OAuth 2.0, the information you'll need to know is listed here:

Authorize URL
Access Token URL
Supported grant typesauthorization_code, refresh_token
Access Token Lifetime3600 seconds
Supported ScopesRefer to table at the bottom of this page.

If you haven't implemented OAuth 2.0 before, read on for more detailed guidance.

Every app is issued an App ID and App Secret. These are shown on your app’s Store Connect page inside your partner account. Your App ID uniquely identifies your app to ServiceM8, and your App Secret serves a similar purpose to a password, allowing your app to prove its identity when required.


Keep it secret, keep it safe

Your App Secret (as its name suggests) must be kept secret. If a third party gets access to it, they’ll be able to impersonate your app 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.

Initiating Authentication

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

with the following parameters encoded in the query string:

response_typerequiredOAuth type. Use “code” when requesting a new access token
client_idrequiredThe App ID of your app
scoperequiredThe list of required scopes (explained below). If requesting multiple scopes, separate them with a space.
redirect_urioptionalThe 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.

For example, if your App ID is 0314159, you would like to request the read_customers and read_jobs scopes, and your OAuth redirect url is, then send your user to the following URL:

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 the call will look like this: GET

Exchanging the Temporary Token

Exchange the temporary token for a permanent access token by making a HTTP POST request to the token endpoint:

with the following POST parameters:

grant_typerequiredOAuth grant type. Use "authorization_code"
client_idrequiredThe App ID for your app.
client_secretrequiredThe App Secret for your app.
coderequiredThe temporary token you received in the prior step.
redirect_urirequiredMust be identical to the redirect URI provided previously

The response will contain your Access Token as well as a Refresh Token.

"access_token": "your_access_token_here",
"expires_in": 3600,
"token_type": "bearer",
"scope": "read_customers read_jobs",
"refresh_token": "your_refresh_token_here"

Using the Access Token

Use the token to access the API. To do this, include the variable access_token as a POST parameter on all requests to the API, or supply the access token, prefixed with "Bearer " on the HTTP "Authorization" header. Access Tokens have a limited lifespan (currently one hour). To continue accessing the account after the token has expired, you need to obtain a new Access Token using the Refresh Token.

Using the Refresh Token

To obtain a new Access Token, make a HTTP POST request to the token endpoint

with the following POST parameters

grant_typerequiredOAuth grant type. Use "refresh_token"
client_idrequiredThe App ID for your app.
client_secretrequiredThe App Secret for your app.
refresh_tokenrequiredThe Refresh Token provided when you obtained the Access Token.

The response will contain your Access Token as well as a new Refresh Token.

"access_token": "your_new_access_token_here",
"expires_in": 3600,
"token_type": "bearer",
"scope": "read_customers read_jobs",
"refresh_token": "your_new_refresh_token_here"


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.

staff_locationsAccess to real-time GPS information about staff
staff_activityAccess to clock on, lunch break and clock off information about staff
publish_smsAccess to send SMS messages to customers and/or staff on your behalf. Note: sending SMS messages will incur account charges.
publish_emailAccess to send Email messages to customers and/or staff on your behalf
vendorAccess to basic account information
vendor_logoAccess to account logo
vendor_emailAccess to account holder email address
read_locationsRead-only access to Location Endpoint
manage_locationsFull access to Location Endpoint
read_staffRead-only access to Staff Endpoint
manage_staffFull access to Staff Endpoint
read_customersRead-only access to Company Endpoint
manage_customersFull access to Company Endpoint
read_customer_contactsRead-only access to CompanyContact Endpoint
manage_customer_contactsFull access to CompanyContact Endpoint
read_jobsRead-only access to Job Endpoint
manage_jobsFull access to Job Endpoint
create_jobsAbility to create jobs on behalf of account. Note: creating jobs may incur account charges.
read_job_contactsRead-only access to JobContact Endpoint
manage_job_contactsFull access to JobContact Endpoint
read_job_materialsRead-only access to JobMaterials Endpoint
manage_job_materialsFull access to JobMaterials Endpoint
read_job_categoriesRead-only access to Categories Endpoint
manage_job_categoriesFull access to Categories Endpoint
read_job_queuesRead-only access to Job Queues Endpoint
manage_job_queuesFull access to Job Queues Endpoint
read_tasksRead-only access to Tasks Endpoint
manage_tasksFull access to Tasks Endpoint
read_scheduleRead-only access to JobActivity Endpoint
manage_scheduleFull access to JobActivity Endpoint
read_inventoryRead-only access to Materials Endpoint
manage_inventoryFull access to Materials Endpoint
read_job_notesRead-only access to job notes
publish_job_notesAbility to add new job notes
read_job_photosRead-only access to job photos
publish_job_photosAbility to add new job photos
read_job_attachmentsRead-only access to existing job attachments, quotes and invoices
publish_job_attachmentsAbility to add new file attachments to jobs
read_inboxRead-only access to inbox messages
read_messagesRead-only access to staff messages
manage_notificationsAbility to read notifications and mark as read
manage_templatesFull access to email, sms and document templates
manage_badgesFull access to create/modify job badges
read_assetsRead-only access to Assets, AssetType and AssetTypeField endpoints
manage_assetsFull access to Asset, AssetType and AssetTypeField endpoints

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.

Connecting your App from the ServiceM8 Add-on Store

If your app is installed from the ServiceM8 Add-on Store 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 disabling the Add-on from within the ServiceM8 Add-on Store.