# Authentication

Pluggy uses two kinds of credentials, depending on where the request is made from:

- **API Key** -- used for server-side requests. It gives full access to all Pluggy API endpoints.
- **Connect Token** -- used from client-side applications (i.e. the [Connect Widget](/docs/connect-widget/introduction)). Its access is limited in scope.

The Connect Token access is limited to only the generated Item resource data ([GET /items/:id](/reference/items-retrieve)), and a reduced access to the data of the recovered Accounts ([GET /accounts?itemId=](/reference/accounts-list)).

So, for example, a newly created Connect Token can't be used to access information that was created previously with a different Connect Token.

For any other kind of request, such as retrieving all the Item related products data, configuring webhooks, [and more](/reference/auth), you'll need to do server-side requests using your API Key.

## Create an API Key

First, you'll need to authenticate with the Pluggy API, using your `CLIENT_ID` and `CLIENT_SECRET`, to [create an API Key](/reference/auth-create) via `POST /auth`.

*Note that these credentials are extremely **sensitive**, so please ensure to do this step in your secured server only.*

This API Key expires after 2 hours and will give you full access to all Pluggy API endpoints.

## Create a Connect Token

Then, with your API Key, you'll have to make a call to [POST /connect_token](/reference/connect-token-create).

> **Important**
>
> The `connectToken` is valid for 30 minutes only.
> The recommended usage is 1-per-connection, so we suggest creating a new one each time you want to create or update an Item.

The usage of this **Connect Token** is identical to the **API Key**: simply pass it in the request authentication header, and the Pluggy API will take care of validating its scope.

> **Warning**
>
> Attempts to access detailed products data using a Connect Token (instead of an API Key) will result in a `403 Forbidden` API response.

### Configuring a Connect Token

When you are creating a Connect Token you can provide some `ItemOptions` that will be passed down to all Items created using the same Connect Token. **They must be sent nested inside the `options` attribute of the request body** -- this is the complete payload:

```json
{
  "options": {
    "webhookUrl": "https://example.com/webhook",
    "clientUserId": "My App UserId",
    "oauthRedirectUri": "https://pluggy.ai/demo",
    "avoidDuplicates": true
  }
}
```

- `webhookUrl`: URL where you will receive all the events of the Items created with this token.
- `clientUserId`: You can use this field to link an Item with your user's identifier.
- `oauthRedirectUri`: URL to redirect the user to after the connect flow.
- `avoidDuplicates`: Avoids creating a new Item if there is already one with the same credentials.

The only other attribute accepted at the root of the body is `itemId`, used when the widget updates an existing Item (see [Updating an Item](/docs/connect-widget/updating-item)).

> **Warning**
>
> Any other property sent at the **root** of the body is ignored. Sending `clientUserId`
> at the root instead of inside `options` still returns `200 OK`, but the value is
> discarded: the Items created with that token will have `clientUserId: null`, and the
> field will also be `null` in the `item/created`, `item/updated` and `item/error`
> webhook payloads.
>
> ```json
> // ❌ Wrong -- clientUserId is silently discarded
> { "clientUserId": "My App UserId", "options": { "avoidDuplicates": true } }
>
> // ✅ Correct
> { "options": { "clientUserId": "My App UserId", "avoidDuplicates": true } }
> ```
>
> If you already have Items created this way, you can backfill the value with
> [PATCH /items/{id}](/reference/items-update).

## Creating an Item

To summarize, the flow to create an [Item](/docs/connections/item) using a `connectToken` is:

1. Your server authenticates with `CLIENT_ID` and `CLIENT_SECRET` to get an API Key.
2. Your server creates a Connect Token and sends it to your client application.
3. Your client application uses the Connect Token to create the Item.

If you are using our [Connect Widget](/docs/connect-widget/introduction), you'll only need to take care of providing the Connect Token -- the rest will be handled by us.

### Keeping a connection reference

When initializing the Connect Widget for your user, you may want to track which user the created connection belongs to. This can be done in a few ways:

- **Connect Widget `onSuccess` event**: When the connection is created and returned, you can recover the `itemId` to store on your side.
- **Webhooks**: After the Item has been successfully created and synchronized, you will receive events. See [Webhooks](/docs/developer-tools/webhooks-ref).
- **Linking your user identifier with an Item**: If you need to link the Item to your user, you can store a reference on our Item by using the `clientUserId`. This value can be provided when creating the `connectToken` or when creating an Item directly through the [Items endpoint](/docs/connections/item).