# Connect Tokens

Browsers and mobile apps are not a safe place for a secret: anything shipped to them can be read.
So the front end never gets your client secret or an API key. It gets a **Connect Token**, a
short-lived credential that your backend creates for one user and one connection.

## Issue it from your backend, for a signed-in user

1. Your server creates an API key with `POST /auth` (see [Credentials](/docs/security/credentials)).
2. Your server creates a Connect Token with [`POST /connect_token`](/reference/connect-token-create),
   from an endpoint that only your **signed-in users** can call.
3. The front end receives the Connect Token and opens [Pluggy Connect](/docs/connect-widget/introduction)
   with it.

Protect that endpoint with your own authentication. Anyone who can call it can open Pluggy Connect
on your behalf and connect accounts to your application.

Recipe: [Issue Connect Tokens from your backend](/recipes/issue-connect-tokens-from-your-backend).
Details: [Pluggy Connect authentication](/docs/connect-widget/authentication).

## What a Connect Token can reach

- The Items created with that token, through [`GET /items/{id}`](/reference/items-retrieve), and a
  reduced view of their accounts, through `GET /accounts?itemId=`.
- Nothing created with another Connect Token.
- No product data: transactions, investments, identity and every other product require an API key.
  A Connect Token gets `403 Forbidden`.

So a Connect Token that leaks exposes at most the connections made with it, and only until it
expires.

## How long it lasts

A Connect Token is valid for **30 minutes**. Create a new one for each connection instead of
caching it or sharing it between users.

While an application is [disabled](/docs/security/credentials#if-a-credential-leaks), its Connect
Tokens are rejected too.

## Options that matter for security

Options go inside `options` in the body of `POST /connect_token`; a property sent at the root is
ignored. See [Configuring a Connect Token](/docs/authentication#configuring-a-connect-token).

| Option | What to do |
| --- | --- |
| `clientUserId` | Set it to an opaque identifier from your system, not an e-mail address or a CPF. It is stored on the Item and sent in every `item/*` webhook payload. |
| `itemId` (at the root) | Scopes the token to one existing Item, to update it. Check that the Item belongs to the signed-in user before you create the token. See [Updating an Item](/docs/connect-widget/updating-item). |
| `webhookUrl` | Must be a public HTTPS URL. It does not send custom headers, so protect it with the [signature](/docs/developer-tools/webhook-security#4-verify-the-signature), or use a webhook created with `POST /webhooks` instead. |
| `oauthRedirectUri` | Must be HTTPS or a deep link into your app. See [OAuth Support Guide](/docs/connect-widget/oauth-support). |

On the widget, leave `includeSandbox` off in production: Sandbox connectors are for testing. See
[Environments and Configurations](/docs/connect-widget/environments).

## Does not protect against

- An endpoint that issues Connect Tokens to anyone: the token is only as safe as the authentication
  in front of it.
- Updating the wrong user's Item: the API scopes the token to the `itemId` you pass, but only your
  backend knows which user owns which Item.

Next: [Webhook security](/docs/developer-tools/webhook-security).