Skip to main content

Glossary

The words that carry weight across the API, Sign in with DFOS, and Protocol sections, defined once. Each entry links to the page that treats it fully.

Action token​

The unit inside a credential's attenuation that names one thing the holder may do. DFOS mints one action token per granted scope — a credential covering read:profile and read:email carries the action set read:profile,read:email on a single resource. The route you call picks the action it needs out of the set; an action the credential does not carry is a 403. Scopes are the developer-facing name for the same facts, and the two are one-to-one. See Scopes and credentials.

App trust​

A user's remembered "trust this app" decision, pinned to a signature of client DID × domain × tier × scope set. It is trust-on-first-use and it authorizes nothing — every check the consent screen runs, runs identically with or without it. All it changes is how much of the screen a returning user re-reads: an unchanged signature within the pinned scopes gets a short card, a wider ask re-consents, and a changed identity voids the pin and says so. Users manage it in Settings → Connected apps. See Trust, and the second sign-in.

Ask proof​

The artifact a local client signs to say it holds the key it is asking to be addressed as: a JWS over the same canonical challenge bytes the user will sign, made by a key current in that client's own chain, and checked before the consent screen renders. It is what substitutes for a domain on the key-proven loopback tier, and therefore what lets a client with no domain be issued a credential at all.

It carries its own registered type, did:dfos:siwd-ask, distinct from the did:dfos:siwd a user's sign-in signature carries; why the two are scoped apart is in Local applications, and the normative rules are in the Sign In With DFOS specification.

Attenuation​

A narrowing attached to a credential: the resource it applies to and the action tokens permitted on it. The word comes from the capability model the credential format borrows — authority is handed down in strictly reduced form, never widened. A Sign in with DFOS credential carries exactly one attenuation, on api:<host>, so it authorizes the actions it lists there and nowhere else. Presenting it against a different host authorizes nothing. See How a credential lives.

Auth key​

A key in an identity's auth set. It signs request proofs and credentials — everything a running server does — but it cannot change the chain itself. This is the key you put on a deployed server, so that a compromised deployment is a revoke-and-re-add rather than a lost identity. Contrast controller key. See Key custody.

Controller key​

A key in an identity's controller set. It signs chain operations — adding or rotating keys, binding a domain, deleting — and so holds the identity's actual authority. It stays on the machine where you ran dfos identity create and never goes near a server. An identity can hold up to 256 of them and any one can sign, which is the only backup mechanism that exists today. See Key custody.

Credential​

The durable artifact a user's approval issues to an app: a signed grant, addressed to the app's DID, that opens the credential-gated routes on the DFOS API. It is not a bearer token — holding one alone opens nothing, because every request also needs a fresh request proof from the app's key. It is issued once, reused across every request, and ends when the user revokes it, which takes effect on the app's next request. In product surfaces the same standing state is called a connection, and the app appears under Settings → Connected apps. See Scopes and credentials.

DfosOrigin entry​

The services entry in an identity's chain that names the one domain the identity claims. Only a controller key can write it, and an identity claims at most one domain. It is half of an origin binding — the claim; the domain has to attest the DID back for the binding to read bound. It shares the chain's open service namespace with the sign-in server entry. See Origin binding.

Exit key​

A key its holder keeps in the controller role on their own DFOS identity's chain — the controller key idea, applied to an account rather than to an app identity. The controller role is the only role it gets, and it is added through a separate, heavier ceremony than a signing key.

DFOS cannot use it: the identity chain here is projected from platform state, and no exit key writes to it. An exit key exists so this identity can continue beyond DFOS. It is deliberately never checked for activity — a dormant exit key is not a problem to fix. See Sessions, grants, and keys.

Genesis operation​

The first operation in an identity chain. Its content hash is what the DID is derived from, which is why a chain can only ever fold into one identity: change the genesis and you have a different DID, not a modified one. Every carried chain is published genesis first, in order. See The protocol.

Grant​

The act of approving a scope set at the consent screen, and the standing state that approval leaves behind. A grant is what a user revokes; the credential is the artifact it produced. See Sessions, grants, and keys.

Identity chain​

The signed, append-only log of operations that is a DFOS identity — genesis, key additions and rotations, service entries. There is no identity record anywhere separate from it: resolve the chain from a relay, verify each operation folds into the next, and you have derived the DID and its current key set for yourself, with no server to trust. Apps get one too, exactly like a user's. See The protocol and Relays & verification.

JWS​

JSON Web Signature — the wire format DFOS signs artifacts in. A signed challenge comes back as a JWS, and every operation in a carried identity chain is a JWS string. It is a format, not a protocol: what makes a DFOS signature meaningful is that the key it names is current in the signer's chain, which is what verification checks. See the Sign In With DFOS specification.

Loopback redirect​

A redirect_uri on localhost, 127.0.0.1, or ::1, which DFOS recognizes as a local tool, agent, or dev server rather than a hosted app. A local port holds no domain, so it can serve no app description: the consent screen invents no name and shows no domain on either shape of this tier.

Two shapes, and the difference is what the request proves. Anonymous loopback names no client_did — nothing about the asking party is known, so it is limited to scope=identity and a set pairing identity with a credential scope is refused rather than quietly narrowed. Key-proven loopback names a client_did and carries that DID's identity chain plus an ask proof over the challenge; that proof stands in for the domain the other tiers rest on, so this shape can be issued a credential — with a 14-day ceiling rather than 90. See Local applications.

Nonce​

A one-time value your app mints and puts in a challenge, then consumes when the signed challenge comes back. It is what makes a replayed callback worthless: the second redemption finds the nonce already gone. Consume it atomically — a read-then-delete race is the whole vulnerability — and take your expectation from state you minted, never from the artifact you are checking. See Wire the sign-in flow.

Origin binding​

A two-sided proof that one party controls both an identity and a domain: the identity's chain claims the domain in a DfosOrigin entry, and the domain publishes the DID back over HTTPS or DNS. Either half alone is a claim anyone could make. Verification folds both into one verdict — bound, stale, broken, or no-claim — and proves control of a domain at verification time, never personhood or endorsement. Any identity can have one — an app you run from the command line, a DFOS account, or a space. See Origin binding for the CLI lane and Verified domains for the in-app one.

Platform key​

The key DFOS holds for a user and signs with on their behalf. It is what lets someone sign in with a code sent to their email rather than a key file, and it is why every standing grant on Settings → Connected apps is something the platform can both mint and revoke. The custody model it names is platform-managed; contrast signing key and exit key. See Sessions, grants, and keys.

Platform-managed​

Key custody where DFOS holds the key and signs on the user's behalf. It is what lets someone sign in with a code sent to their email, and it is why the platform can both mint a grant for them and revoke it for them. Every standing grant in Settings → Connected apps is platform-managed. Contrast self-custodied. See Sessions, grants, and keys.

Request proof​

A fresh, short-lived signature an app makes for one API request, covering that exact method, host, path, and a hash of the body. It is the other half of a gated request: the credential says what the app may do, and the proof says the app is the one doing it, and doing exactly this. A proof is good for about a minute and authorizes nothing beyond the request it names. See Authentication and the DFOS API-AUTH specification.

Scope​

One thing an app asks for at the consent screen, and the developer-facing name for what a credential ends up carrying. scope is a space-separated set on the authorize URL; each token renders as its own platform-authored consent line, and one unknown token refuses the whole request rather than silently granting the valid part. Today: identity, which issues nothing, plus read:profile, read:email, and read:memberships. See Scopes and credentials.

Self-custodied​

Key custody where the user holds their own key, so DFOS is never in the signing loop. Nothing is issued here, nothing is recorded here, and there is nothing here to revoke — those sign-ins are managed wherever they were created. What decides the plane is whose key signed, not what kind of software asked: a command-line tool signing against a relay with a key you hold is self-custodied, and the same tool taking a DFOS credential is not. A signing key on a DFOS account is this plane. Contrast platform-managed. See Sessions, grants, and keys.

Sign-in server​

The DfosAuthorizationServer entry in an identity's chain: the service entry naming the authorize origin that speaks for that DID. A client that wants to sign somebody in resolves their chain, reads this entry, and appends /authorize to the origin it names — which is how sign-in is discovered from the identity itself rather than configured out of band. One entry, or none: zero, more than one, or an endpoint that is not a bare http(s) origin all name nothing, and a client falls back to an explicitly configured endpoint rather than picking. Every DFOS-hosted identity carries one. Like DfosOrigin it rides the chain's open service namespace, so a core verifier treats it as an unrecognized type and passes it through. See the Sign In With DFOS specification.

Signing key​

A key a user holds themselves, on their own machine, added to their DFOS identity's chain through the key-add ceremony. It carries the auth and assert roles — it signs the user in, and signs claims as them — and cannot change the chain itself; that is an exit key. DFOS never sees its private half, so what it signs is self-custodied and nothing it does appears under Settings → Connected apps.

The ceremony's two halves are deliberately split: a CLI proves possession of the key, and the key's owner then adopts it in their own settings after comparing fingerprints. Neither half alone adds anything to a chain. See Key proof for the CLI-facing routes and Sessions, grants, and keys for the whole model.

Tier​

How the platform resolved the app asking at the consent screen, and therefore what it is willing to say about it — jit or loopback. It is recorded on the credential and readable at GET /v1/credential, which has the full table.

The tier is a statement about proof of who is asking, never about capability: both get the same scopes, the same credentials, and the same API access. What changes is the consent screen's copy — a domain leading the card, or a platform-authored phrase where there is none — and, on loopback, a 14-day expiry ceiling instead of 90 days. Nothing here is a vouch: DFOS operates no registry and stands behind no app's name. tier is an open enum on the wire; treat an unrecognized value as an opaque string. See Two tiers, and the tier is only about trust.