Secrets
Keep, rotate with an overlap, and revoke client secrets.
What a secret is
A web app has a client secret, which starts with psk_. The app uses it at the token endpoint to prove that it is your app. PulseID keeps only a hash of it, so the secret is shown once, when you create the app or rotate the secret. Copy it then. If you lose it, rotate to get a new one. A public app has no secret.
Keep the secret on your server, in an environment variable or a secret store. Never put it in browser code, a mobile app or a repository. A developer in the organization, or an admin or the owner, can rotate and revoke secrets.
Rotate with an overlap
Rotating makes a new secret the current one. The secret it replaces keeps working for the overlap you choose, so you can deploy the new secret without a gap in sign-in.
| Overlap | When to use it |
|---|---|
| None | The old secret stops working at once. Use it when a secret leaked. |
| 1 hour | For a deploy that finishes quickly. |
| 1 day | For an app that deploys in stages. |
| 7 days | The longest overlap. For a slow rollout across many servers. |
- Rotate, and choose an overlap long enough to deploy.
- Copy the new secret and put it where your app reads it.
- Deploy, then check that people can still sign in.
- The old secret stops at the end of the overlap. To end it sooner, revoke it.
The two-secret limit
An app can have 2 live secrets at once: the current one and one that is still in its overlap. While two live secrets exist you cannot rotate again. Revoke one, or wait for the older one to expire. An app can be rotated 10 times a day.
Revoke
Revoking ends one secret at once, with no overlap. A token request that uses it fails with invalid_client. If you revoke the only live secret, the app cannot get tokens, so nobody can sign in to it, until you rotate to make a new one. An app with no live secret also fails with invalid_client.