Skip to main content

Security

The M2M API is a server-to-server credential. Treat it accordingly.

Secret handling​

  • Never put CLIENT_SECRET in source control, browser-bundled code, or mobile apps. It is a backend-only credential.
  • Store it in your secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault). Avoid raw .env files outside of local development; if you must use one, add it to .gitignore and make sure the build system never bakes it into images.
  • Restrict who can read the secret to as few service accounts / engineers as possible.

Transport​

  • HTTPS only — both to the Keycloak token endpoint and the API. Reject any configuration that points to http://....
  • If your security policy supports outbound egress filtering, restrict your backend's outbound traffic to the two Persium hostnames you were provisioned.

Rotation​

Rotate CLIENT_SECRET periodically — Persium recommends every 90 days, and always after a suspected leak or staff offboarding.

The rotation flow is operator-assisted:

  1. Tell Persium you want to rotate.
  2. Persium issues a new secret.
  3. You hold both secrets briefly: deploy the new one while the old is still valid.
  4. Persium retires the old secret on your signal.

There is no zero-downtime self-service rotation — you must coordinate with Persium. Plan the rotation during a low-traffic window.

Scope​

Each CLIENT_ID is scoped to exactly one organisation. You cannot use M2M credentials to access another organisation's data, even if you know its UUIDs (you will get 404).

If your business needs cross-organisation access — e.g. a parent company integrating data from several subsidiaries — talk to Persium. That's a different provisioning conversation.

Incident response​

If you suspect the secret has leaked (e.g. a public commit, a lost laptop, a contractor offboarded without de-provisioning):

  1. Treat it as compromised even if you have no evidence of abuse.
  2. Contact Persium support immediately to rotate.
  3. While you wait, you can keep using the old secret — Persium can force-revoke it as part of the rotation if needed.
  4. After rotation, audit the leak's blast radius (logs, git history, build artefacts) and remove the old secret from anywhere it persists.