Authentication & Access

Outline

You can use the SurfaceScout API programmatically to do actions on behalf of your business.

The general steps involve

• Authentication to receive an access token.

• Interactions on behalf of a business using the access token.

• Re-authentication once the access token expires.

Important: Currently only a limited number of endpoints are enabled for access via OAuth2.0 machine-to-machine client. Please find the list of such endpoints here.

We will enable further endpoints for programmatic access as our customer use-cases develop.

Getting started

To access the SurfaceScout API, you need an account with an admin role. Your dedicated Customer Success Manager at LiveEO can help you with this. Once logged into SurfaceScout, open the configuration panel on the right-hand side of the desktop app.

Retrieve an access token

With these client credentials, you can programmatically create an access token for temporary access to the API. For enhanced security, the access token will expire after one day. After that, you can use the client credentials again to create a new access token.

You request a token with the following HTTP request (make sure to insert your own client ID and client secret)

curl --request POST \
  --url https://api.surfacescout.liveeo.io/m2m/token \
  --header 'Content-Type: application/json' \
  --data '{"client_id":"<YOUR_CLIENT_ID>","client_secret":"<YOUR_CLIENT_SECRET>","grant_type":"client_credentials"}'

On success, this will respond with an access token as follows:

{
  "access_token": "<JWT_VALUE_HERE>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read:example"
}

Interactions after authentication

Next, use the access_token from the previous section's response body to authenticate and interact with the SurfaceScout API. For example,

curl https://api.surfacescout.live-eo.com/insights \
  --header 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE'

Example response

You should receive an HTTP status code of 200 and, if you have not yet created any plots using the SurfaceScout Web Application, the response body will be an empty array.

[]

Access token expiry and re-authentication

After the access token has expired, the SurfaceScout API will respond with an HTTP status code of 401 Unauthenticated. Once that happens, you will need to re-authenticate using the Client Credentials Flow described in the section "Retrieve an access token" above.

We kindly ask you to reuse the Access Token instead of re-authenticating on every request, if possible.

Next steps

From here, you can interact with the SurfaceScout API on behalf of your business by including the access token in the Authorization header of your HTTP requests as explained above.

SurfaceScout API Reference and Limitations

Please refer to API Reference specifications and limitations:

1. Maximum Payload Size: 10 megabytes per request.

2. Insight photo size of the insights : 1000 x 1000 px

3. More than 5 invalid request : 1 min wait time

Support

For any support requests, questions, or comments, please submit a request, or email us directly at [email protected]. Our dedicated support team will respond promptly to address your needs and provide the necessary assistance.