Looking for the previous documentation?Go to v1.docs.pluggy.ai

Connect Tokens

Why the front end only ever gets a Connect Token, how to issue one from your backend, what it can reach, how long it lasts, and the options that matter for security.

View as Markdown

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).
  2. Your server creates a Connect Token with POST /connect_tokenAPI, from an endpoint that only your signed-in users can call.
  3. The front end receives the Connect Token and opens Pluggy Connect 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. Details: Pluggy Connect authentication.

What a Connect Token can reach#

  • The Items created with that token, through GET /items/{id}API, 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, 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.

OptionWhat to do
clientUserIdSet 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.
webhookUrlMust be a public HTTPS URL. It does not send custom headers, so protect it with the signature, or use a webhook created with POST /webhooks instead.
oauthRedirectUriMust be HTTPS or a deep link into your app. See OAuth Support Guide.

On the widget, leave includeSandbox off in production: Sandbox connectors are for testing. See Environments and Configurations.

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.

Was this page helpful?