# 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="../../connectors/helpers/webhook-helper#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.