# Locoia API Authentication - Personal Access Token

## Creating a Personal Access Token

### In Locoia

Go to your avatar (upper right corner) > **User** > [**Personal Access Token**](https://app.locoia.com/user-preferences?activeTab=personalAccessTokens)**.**

There you can create new access tokens, update and regenerate existing ones with full flexibility.

{% hint style="warning" %}
The token itself is only visible right after creating a personal access token. In case you didn't save it, you can generate the token. The old token will then be invalidated.
{% endhint %}

### Using the API

{% hint style="info" %}
We recommend to generate and manage personal access tokens directly in our app for, however, you can use our API for that as well.
{% endhint %}

In order to create a personal access token via API the following endpoint needs to be used:

## Create personal access token

<mark style="color:green;">`POST`</mark> `https://api.locoia.com/v1/personal-access-tokens`

The personal access token can be defined with granular scopes and an expiration date.

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Token |

#### Request Body

| Name                                         | Type   | Description                                                   |
| -------------------------------------------- | ------ | ------------------------------------------------------------- |
| expiration<mark style="color:red;">\*</mark> | Int    | Number of days until expiration. Use `null` for no expiration |
| scopes<mark style="color:red;">\*</mark>     | List   | List of scopes                                                |
| note<mark style="color:red;">\*</mark>       | String | Describe purpose, (max 255 characters)                        |

{% tabs %}
{% tab title="201: Created " %}

```javascript
{
  "id": "UUID",
  "token": "Token",
  "expiration": "Expiration Datetime",
  "note": "String",
  "last_used": null,
  "scopes": [
    "Scope1",
    "Scope2"
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The token itself is only visible right after creating a personal access token, after that it is impossible to retrieve it from the API.
{% endhint %}

You can also create it directly in Locoia with [this Community Library Flow](https://app.locoia.com/#/community-library?page=1\&perPage=10\&nameSearchString=Create%20a%20Personal%20Access%20Token%20for%20Locoia\&sortProp=reference\&sortOrder=ascending).

One can regenerate a token with by sending the following `POST` request:

## Regenerate personal access token

<mark style="color:green;">`POST`</mark> `https://api.locoia.com/v1/personal-access-tokens/{{ token_id }}/regenerate`

Regenerate or extend the expiration of an already created personal access token.

#### Path Parameters

| Name                                        | Type   | Description                                   |
| ------------------------------------------- | ------ | --------------------------------------------- |
| token\_id<mark style="color:red;">\*</mark> | String | ID of personal access token to be regenerated |

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Token |

#### Request Body

| Name                                         | Type | Description                                              |
| -------------------------------------------- | ---- | -------------------------------------------------------- |
| expiration<mark style="color:red;">\*</mark> | Int  | Number of days until expiration `null` for no expiration |

You can list all token with

## Get personal access tokens

<mark style="color:blue;">`GET`</mark> `https://api.locoia.com/v1/personal-access-tokens`

List all personal access tokens of the user.

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | String | Bearer Token |

## Scopes

The following scopes are available:

| Scope Name      | Entites                                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| automation      | <ul><li>Flows</li><li>Flow Runs</li><li>Flow Run Steps</li><li>Run Flows</li><li>Connector Auths (Read only)</li><li>Env Variables (Read only)</li><li>File Uploads (Read only)</li></ul> |
| company         | <ul><li>Env Variables</li><li>File Uploads</li><li>Teams</li><li>Users</li></ul>                                                                                                          |
| connector\_auth | <ul><li>Connector Auths</li></ul>                                                                                                                                                         |
| connectors      | <ul><li>Connectors</li><li>Connector Actions</li></ul>                                                                                                                                    |
| dashboard       | <p></p><ul><li>Dashboards</li><li>Data Sources</li><li>Forecasts</li><li>Insights</li><li>Transforms</li></ul>                                                                            |
| embed           | <ul><li>Embeds</li></ul>                                                                                                                                                                  |

There are different access levels based on the scope extension:

<table><thead><tr><th>Scope Extension</th><th>Supported Scopes<select multiple><option value="e6b177a113fa4d3b97b3427827844c59" label="automation" color="blue"></option><option value="866b994c082242db96ed3d8b3d36b681" label="company" color="blue"></option><option value="e58c91d3e5e34ce98f8397ed59c63b1e" label="connector_auth" color="blue"></option><option value="bc5dd60c15cb4958bffbf8228a581607" label="connectors" color="blue"></option><option value="d7f9f6a012c14f3a984d9876e98b4d09" label="dashboard" color="blue"></option><option value="d1cd9d04d9504e65b34dcc78ad9ee299" label="embed" color="blue"></option></select></th><th>Operations</th><th>Example</th></tr></thead><tbody><tr><td><em>None (leave empty)</em></td><td><span data-option="e6b177a113fa4d3b97b3427827844c59">automation, </span><span data-option="866b994c082242db96ed3d8b3d36b681">company, </span><span data-option="e58c91d3e5e34ce98f8397ed59c63b1e">connector_auth, </span><span data-option="bc5dd60c15cb4958bffbf8228a581607">connectors, </span><span data-option="d7f9f6a012c14f3a984d9876e98b4d09">dashboard, </span><span data-option="d1cd9d04d9504e65b34dcc78ad9ee299">embed</span></td><td>CRUD - Create, Read, Update, Delete</td><td><code>connector_auth</code> - the token can create, read, update, and delete all Connector Auths to which the user who created the token has access to</td></tr><tr><td>:manage</td><td><span data-option="e6b177a113fa4d3b97b3427827844c59">automation, </span><span data-option="866b994c082242db96ed3d8b3d36b681">company, </span><span data-option="e58c91d3e5e34ce98f8397ed59c63b1e">connector_auth, </span><span data-option="bc5dd60c15cb4958bffbf8228a581607">connectors, </span><span data-option="d7f9f6a012c14f3a984d9876e98b4d09">dashboard, </span><span data-option="d1cd9d04d9504e65b34dcc78ad9ee299">embed</span></td><td>CRU - Create, Read, Update</td><td><code>connector_auth:manage</code> - the user can do all of the above, except for deleting</td></tr><tr><td>:view</td><td><span data-option="e6b177a113fa4d3b97b3427827844c59">automation, </span><span data-option="866b994c082242db96ed3d8b3d36b681">company, </span><span data-option="e58c91d3e5e34ce98f8397ed59c63b1e">connector_auth, </span><span data-option="bc5dd60c15cb4958bffbf8228a581607">connectors, </span><span data-option="d7f9f6a012c14f3a984d9876e98b4d09">dashboard, </span><span data-option="d1cd9d04d9504e65b34dcc78ad9ee299">embed</span></td><td>R - Read</td><td><code>connector_auth:view</code> - the user can only read the Connector Auths</td></tr><tr><td>webhook_run</td><td><span data-option="e6b177a113fa4d3b97b3427827844c59">automation</span></td><td>Trigger Webhook Flows</td><td><code>automation</code> - the token can trigger all Webhook Flows in the account (alternative to Flow specific <a href="/pages/-McyrtPMyC9whUA8i4TP#webhook-security-bearer-token">webhook tokens</a>)</td></tr></tbody></table>

## Using Personal Access Token

To authenticate with the token, simply specify it in the Authorization header like this: `Authorization: Bearer {{ token }}` or setup a Connector Auth for Locoia within the Locoia app and then use the token there.


---

# Agent Instructions: 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:

```
GET https://docs.locoia.com/api/authentication-with-our-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.