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

Security overview

The security practices every Pluggy integration should follow: where your credentials live, what the front end may hold, how to trust a webhook, who on your team can change what, and how to handle your users' data.

View as Markdown

Your Pluggy credentials reach your users' financial data. Pluggy runs the connections to the institutions, keeps each Item's credentials and data, and delivers your webhooks, signed once you turn signing on. Your side of the integration is yours to secure: your credentials, the tokens you hand to the front end, your webhook endpoint, your team, and the data you copy into your own systems.

Each section below is a summary with a link to the page that has the details. The checklist at the end sums them up.

Credentials stay on your server#

Your application's client secret, and the API keys your server creates with it, have full access to the Pluggy API. Keep them in a secrets manager or a server environment variable, reuse each API key until it expires, and use separate applications for development and production. Generating a new client secret stops the old one immediately but does not revoke API keys created before it.

Details: Credentials and API keys. Recipe: Rotate your client secret.

The front end gets a Connect Token, never an API key#

Your backend creates a Connect Token for a signed-in user, and the front end opens Pluggy Connect with it. It lasts 30 minutes, reaches only the Items created with it, and cannot read product data. Set clientUserId to an opaque identifier, and leave includeSandbox off in production.

Details: Connect Tokens. Recipe: Issue Connect Tokens from your backend.

Verify every webhook notification#

Your webhook endpoint is public, so treat every request as untrusted until it passes your checks. Combine the layers: an HTTPS endpoint, a secret in the webhook's headers, and the X-Pluggy-Signature HMAC signature, which proves that Pluggy sent the notification and that its body was not altered. Then check clientId and read the current state with your API key instead of trusting the payload. Source-IP filtering is an extra layer, never the only one.

Details: Webhook security. Recipe: Authenticate webhook notifications with a header secret.

Only the right people manage your applications#

A team has three roles. Owners and Admins generate client secrets and manage webhooks; only Owners disable or delete applications and manage the webhook signing secret. Keep OWNER and ADMIN for the people who need them, and rotate secrets when someone who could see them leaves.

Details: Team access.

Let Pluggy Connect collect bank credentials, so they never pass through your servers. Let users disconnect, and delete the Item when they do: that wipes its credentials, revokes the consent and deletes its data. Remove your own copy on item/deleted, and store only what your product uses.

Details: Data protection.

Report a vulnerability#

If you find a security vulnerability in Pluggy, write to security@pluggy.ai. The same contact is published in our security.txt.

Checklist#

AreaCheck
CredentialsThe client secret lives only in a secrets manager or server environment variable.
CredentialsNo client secret or API key is in front-end code, mobile apps, repositories or logs.
CredentialsYour server reuses each API key until it expires.
CredentialsDevelopment and production use separate applications.
CredentialsYou know how to generate a new client secret, where to deploy it, and how to disable the application if an API key leaks.
Front endThe front end receives only Connect Tokens, created by your backend for an authenticated user.
Front endclientUserId is an opaque identifier, not personal data.
Front endincludeSandbox is off in production.
WebhooksYour endpoint verifies X-Pluggy-Signature over the raw body, with a 5-minute tolerance.
WebhooksWebhooks created with POST /webhooks carry a secret header that your endpoint requires.
WebhooksYour endpoint ignores notifications for other clientIds, answers 2xx quickly and reads the data with your API key.
AccessOnly the people who need it are OWNER or ADMIN of your team.
AccessMembers who leave are removed, and the secrets they could see are rotated.
DataUsers can disconnect, and disconnecting deletes the Item.
DataYou remove your copy of the data on item/deleted.
Was this page helpful?