> For the complete documentation index, see [llms.txt](https://docs.live-eo.com/surfacescout/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.live-eo.com/surfacescout/surfacescout-api/authentication-and-access.md).

# Authentication & Access

#### Outline <a href="#outline" id="outline"></a>

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 endpoints here](https://api.surfacescout.liveeo.io/api#\\)
>
> We will enable further endpoints for programmatic access as our customer use-cases develop.

#### Getting started <a href="#getting-started" id="getting-started"></a>

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 **Settings** from the menu in the desktop app and go to the **API Access** tab.

<figure><img src="/files/8GaPiAO9LPwBik2akGYq" alt=""><figcaption></figcaption></figure>

**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)

<a class="button secondary">Copy</a>

```
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:

<a class="button secondary">Copy</a>

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

#### Interactions after authentication <a href="#interactions-after-authentication" id="interactions-after-authentication"></a>

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

<a class="button secondary">Copy</a>

```
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.

<a class="button secondary">Copy</a>

```
[]
```

#### Access token expiry and re-authentication <a href="#access-token-expiry-and-re-authentication" id="access-token-expiry-and-re-authentication"></a>

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 <a href="#next-steps" id="next-steps"></a>

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** <a href="#tradeaware-api-reference-and-limitations" id="tradeaware-api-reference-and-limitations"></a>

Please refer to [API Reference specifications](/surfacescout/surfacescout-api/api-reference.md) 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 <a href="#apiaccess-support" id="apiaccess-support"></a>

For any support requests, questions, or comments, please[ submit a request](https://live-eo-helpdesk.atlassian.net/servicedesk/customer/portal/2), or email us directly at [support@live-eo.com](mailto:support-tradeaware@live-eo.com). Our dedicated support team will respond promptly to address your needs and provide the necessary assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.live-eo.com/surfacescout/surfacescout-api/authentication-and-access.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.