Sessions, grants, and keys

When you sign in to something with your DFOS identity, a session starts somewhere. Where that somewhere is decides whether DFOS can show it to you and end it for you. What decides that, underneath, is which key signed — so this page covers both: the two planes a session can live on, and the three kinds of key that put it on one or the other.

There are two planes, and only one of them appears in your settings.

Grants the platform manages

This is what happens when you press a "Sign in with DFOS" button on another app. DFOS holds a platform key for you, so DFOS shows you the consent screen and, once you approve, signs you in to the app. An app can ask for several things at once; you approve them together on one screen.

A grant has a where as well as a what. The consent screen says one of three things: In all your spaces, which includes spaces you join later and tells the app which spaces you belong to; In these spaces, with each one named; or Choose where — a picker over your own spaces when the app named none, with nothing ticked for you.

Because the platform issued it, the platform can end it:

• Settings → Connected apps lists every standing grant, the app it went to, and what that app is allowed to do — one line per thing, the same lines you read on the consent screen, plus the same In all your spaces or In: A, B line.
• Disconnecting one app, or all of them at once, takes effect on the app's next request, which then fails.
• Grants carry a 90-day expiry, shown on each card, or 14 days for a local application. That catches grants nobody got around to revoking. It is not the lever you use to end access.

Revoking ends future access. It does not un-share what the app already read, so disconnect when you're done with an app rather than as cleanup later.

Trusting an app to skip the screen

On the consent screen there's a checkbox: "Trust this app — skip this screen next time." Tick it and the next sign-in to that app shows a short card instead of the full one — who's asking, who you are, what it already has, Approve and Deny.

Trusting an app grants it nothing. Every check DFOS runs on a sign-in runs exactly the same way whether you trusted the app or not. The only thing that changes is how much of the screen you're asked to read again. An app that stops being able to prove who it is gets refused whether you trusted it or not.

Four things bring the full screen back:

• The app asks for something new. More than you approved last time means you read and approve the new part. Asking for less than last time doesn't — you already said yes to more.
• The app's identity changes. If a different identity starts answering for a domain you trusted, DFOS removes your trust before showing you anything, and the screen leads with the change: the identity you trusted, struck through, against the one asking now. That can be a routine key change on the app's side, or a domain that changed hands. Read it before you approve.
• The app leaves the choice of spaces to you. An ask that doesn't name its spaces always shows the full screen, so you can pick them.
• You remove the trust yourself.

In Settings → Connected apps, a trusted app is marked Trusted and carries a Remove trust button. Removing trust ends nothing — the app keeps whatever you granted it, and simply asks for full approval next time. Disconnect is the lever that actually ends access, and disconnecting removes the trust too.

Apps running on your own machine can be trusted only if they proved which identity they are. One that proved nothing about itself can never be trusted.

A tool on your own machine can be on this list too

Most cards on Connected apps name a domain. Some say Local application instead, and those are command-line tools, agents, and desktop apps that signed in from your own machine.

They belong here for the same reason every other card does: DFOS signed you in, so DFOS can end it. The card leads with "Local application" and the tool's identity address rather than a domain. That address tells you which tool it is, not where the software came from. Revoke one exactly as you would any other.

DFOS emails you when this list changes

Three moments send you mail, so a change to what apps hold on your behalf reaches you out-of-band rather than only on a screen you'd have to think to open:

• An app connected — sent when you approve a sign-in, naming the app's domain and listing what you granted, one line per thing.
• An app was disconnected — sent when you disconnect a single app.
• All apps were disconnected — sent when you disconnect everything at once.

The connect email is the one that matters most: if it arrives and you did not approve anything, someone else reached your account, and disconnecting is the first move. These are always sent; there is no setting to turn them off.

Each disconnect email says the same thing the screen does: access ends on the app's next request, not at some later expiry.

Sessions the platform never sees

The Connected apps list shows exactly what DFOS issued, and only that.

When you sign in with a signing key you hold yourself, DFOS is never involved. Nothing is issued here, nothing is recorded here, and there is nothing here to revoke. Those sessions are real, and you end one in the app or tool that started it.

So read the list for what it is: an empty Connected apps screen means DFOS is holding no standing grants on your behalf. It is not a statement about every session that exists in your name.

The three kinds of key

Three kinds of key can sign for your DFOS identity, and they are kept apart on purpose. You see all of them in Settings → DFOS Protocol. See The protocol for what the identity itself is.

Key	Who holds it	What it can do
Platform key	DFOS	Signs on your behalf, in the app and at the consent screen
Signing key	You	Signs in as you, and signs claims as you
Exit key	You	Changes the identity itself

Platform keys

A platform key is one DFOS holds and signs with on your behalf. You never handle it and there is nothing to set up. Your account has one from the moment it exists. It is why you can sign in with a code sent to your email rather than a key file, and why every grant on Connected apps is one DFOS can show you and end for you.

Signing keys

A signing key is one you hold, on your own machine. DFOS never sees its private half. It can sign you in to things as you, and sign content and claims as you, but it cannot change the identity itself. Each key carries a label you choose, usually the machine it lives on, and you can rename or remove one at any time. Removing a key ends what it can sign for.

Adding one

To add one, press Add key under Signing keys. DFOS gives you a short code, good for ten minutes, and a command to run on the machine the key should live on. You then compare a short phrase of words on both screens and approve the key in Settings. Nothing is added until you approve it.

Exit keys

An exit key is one you hold that can change the identity itself, from outside DFOS. Adding one gives it that role and nothing else. DFOS cannot use this key. It exists so this identity can continue beyond DFOS, independent of us.

To add one, press Add exit key under Exit keys, its own button separate from signing keys. You tick an acknowledgement before DFOS gives you a code, and the rest works the same way as adding a signing key.

Two things worth stating plainly:

• It is never checked for activity. DFOS does not warn you that it has gone unused. An exit key you never use is an exit key doing its job.
• It is only useful if you still have it. Keep it somewhere you would still reach if you lost access to this account.

The command-line side of adding keys, rehearsing a recovery, and checking that a machine still holds its keys is covered in Key custody.

Related

• Agents & connected apps — what a connected agent and an app sign-in each get, and how they differ.
• Accounts — your identity, your profile, and the privacy controls around them.
• Scopes and credentials — the developer side: how a credential is issued, spent on each request, and revoked.
• Key proof — the developer side of the signing-key ceremony: the two API routes a CLI talks to while a key is being added.