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#
- Your server creates an API key with
POST /auth(see Credentials). - Your server creates a Connect Token with
POST /connect_tokenAPI, from an endpoint that only your signed-in users can call. - 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, throughGET /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.
| 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. |
webhookUrl | Must 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. |
oauthRedirectUri | Must 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
itemIdyou pass, but only your backend knows which user owns which Item.
Next: Webhook security.
