Keys: rotation, revocation and expiry
What happens when your team's key changes, and what to do in your backend.
When a key is rotated
Section titled “When a key is rotated”Neurologyca rotates a key when someone who knew it leaves the team, when it may have leaked, or before it expires. Rotation is immediate:
- the previous key stops minting tokens;
- a token minted from it is refused on its next request;
- an open event stream ends with
stream.endand the reasoncredential_rotated, and cannot be reopened with the same token.
Every active member of the team receives an email (it never contains the key). Then:
- Reveal the new key in Your account.
- Replace it in your backend’s secrets and deploy.
- Mint a new token with
POST /token. - Reopen the event streams that ended, with the new token.
When a team is revoked
Section titled “When a team is revoked”Its key stops working for good and the team is disabled in DevLab: tokens minted from it are refused and open streams end with credential_revoked. Revoking withdraws the key, not the people: its members keep their accounts and can still sign in, but see no key; in Your integration they see their milestones and their organization’s protocols in read-only mode, without the kit. To remove someone’s access, Neurologyca disables their account (see below). Revoking does not send an email today.
When someone leaves the team
Section titled “When someone leaves the team”Neurologyca disables their account, and their sessions end at once. A key they copied keeps working until the key is rotated: ask Neurologyca to rotate it.
Expiry
Section titled “Expiry”Keys created through DevLab expire one year after they were created or last rotated. DevLab shows the expiry date in Your account (Check, one click per key) and, to an organization admin, in Your integration → Status (per team). When less than 30 days are left, the date carries “< 30 days” (and, for your own team’s key, Your account warns you): ask Neurologyca for a rotation before then. Once the date has passed, the key shows Expired. An expired key behaves like a revoked one (credential_expired); rotating renews the year.
If your organization is suspended
Section titled “If your organization is suspended”While Neurologyca has your organization suspended in Engine, none of its keys works: your backend’s POST /token gets the same 401 as with a wrong key, and DevLab (your account, the kit and the playground) says Suspended and answers 403 tenant.suspended. Rotating a key does not help. Nothing is deleted: when Neurologyca reactivates it, the same keys can be used again. If the organization has been removed, revealing or downloading a key answers 409 tenant.deleted.
What your backend sees
Section titled “What your backend sees”POST /token with a rotated, revoked or expired key (the body is always the same):
{ "status": 401, "body": { "code": 401, "message": "Invalid credentials." } }Any other request with a token minted from that key: 401, an empty body and this header:
{ "status": 401, "emptyBody": true, "wwwAuthenticate": "Bearer error=\"invalid_token\"" }An open event stream, as it ends after a rotation:
{ "events": ["connected", "stream.end"], "reason": "credential_rotated" }Only after idle_timeout can you reopen a stream with the same token; after a credential_* reason, mint a new one. The same happens when Neurologyca changes a key’s scope: it applies at once, tokens minted before are refused and open streams end with credential_scope_changed.
Deferred processing credentials
Section titled “Deferred processing credentials”If your organization uses Neurologyca’s processing service for deferred mode, it has two more credentials, separate from the Engine keys: the processor key, which your backend presents to the service, and the webhook secret, which the service signs its notices with. There is one pair per organization, shared by every team: each team’s backend uses it, and each active team gets the current pair in its recording starter with Include my key and the processor credentials. Only your organization’s admin team reveals and rotates them, in Your account (see Your DevLab account); Neurologyca does not reveal them.
Rotation has two steps, so your backend never stops working:
- Generate new values (the key, the secret or both). They stay pending: the service keeps accepting the current ones.
- Deploy them in the backend of every team that uses deferred processing and press Activate straight away. DevLab sends them to the service within seconds; until it confirms them, the service accepts the previous ones.
Rotating only the key has no risky window: the recordings in progress no longer use it, and a submission the service refuses is retried by your backend. Rotating the secret does: the notices of the recordings in progress are signed with the new secret as soon as you activate, and a notice that a backend refuses by signature is not retried: it is lost, and only getJob().webhook.status shows it. So Activate tells you how many are in progress and asks you to confirm that the backend of every team already has the new secret. To close that window, a backend can accept both secrets while it lasts: createWebhookHandler and createProcessorTokenHandler take a single secret, so mount a second instance with the previous secret: copy the request before the first one reads it (const copy = req.clone()), and pass the copy to the second only when the first answers 401. Remove it once the new values are active.
The service also publishes the IP it calls you from. Limit your three routes to it as defense in depth: the IP does not authenticate. Verifying the signature is mandatory, and the SDK does it for you.
If a processor credential leaks
Section titled “If a processor credential leaks”There is no one-step “rotate now”. The procedure:
- Neurologyca turns off deferred processing for your organization in its admin panel. The service rejects the recordings your backend sends from then on with
403 E_CLIENT_DISABLED(the ones in progress finish). Your teams can’t record in Deferred in the DevLab playground either until it is turned back on. - Your organization admin rotates in two steps while it is still turned off: generate, deploy and activate in Your account. The service keeps rejecting your recordings in the meantime, so the leaked values are never accepted again.
- Neurologyca turns it back on, and the service comes back already with the new values.
Tell Neurologyca as soon as you suspect a leak.
In DevLab
Section titled “In DevLab”Inside DevLab, your next request uses the new key. An open event stream ends with credential_rotated, as it does for your backend.
If a key that DevLab keeps for you is rotated or revoked outside DevLab, DevLab can no longer use it, and the playground answers 403 gateway.team_unavailable. Ask Neurologyca to rotate or revoke these keys instead.