The token service
Think of an office building with a front desk. You do not get a master key. You show who you are at the desk, and the desk hands you a visitor badge: it names you, it opens one door, and it stops working in a few minutes. If you need to go back in later, you ask the desk again. If someone takes your badge, it is useless to them almost at once, and the desk can tell every door to turn you away.
The token service is that front desk for your workspace. Each workspace gets one of its own, and it runs in your workspace's own environment, so the badges your runtimes trust are made by you, not by Fathym.
This page is written to what is being built, not to what exists. The service itself is not built: its program is an
empty scaffold, and nothing is deployed to any workspace. Only a few of the pieces it will stand on exist, and they
exist only in Fathym's eac library on a development branch, not yet published or released: a signing key held
outside the process, a used refresh pass ending the whole sign-in chain (with the 10-second retry grace described
below), and, in part, the sign-in exchange that accepts a person's or job's token from another issuer and a client
proof that works only once. Anything still being decided is marked being decided.
What it does
- Hands out short badges. A badge lives 5 minutes; only a job's badge can live longer, up to 60 minutes (see Who calls it). It names your workspace's own token service as the one that issued it, and exactly one runtime as the door it opens: a badge made for the surface runtime does not work at your workspace's API.
- Signs with a key it never holds. The signing key is made in your workspace's Key Vault when you press Deploy, and it cannot be copied out. The vault does the signing; neither the service nor OpenX ever sees the key. The key starts in a standard Key Vault; a hardware-held key in a Premium vault is a later phase. How often the key rotates is being decided.
- Keeps people signed in safely. A person who signs in to your directory gets a refresh pass that works once. Each use returns a new badge and a new pass. If a pass that was already used comes back, someone has copied it, so the whole sign-in ends at once and the person signs in again. A retry within 10 seconds (for example after a network drop) gets the same answer back instead of ending the sign-in.
- Keeps a revoke list that your runtimes read, so a sign-in or token that was ended is turned away everywhere.
It runs wherever your workspace's API runs: in your own Azure subscription, or in Fathym's shared space for a workspace with no cloud. Its settings live in App Identity. Where a workspace with no cloud sees its status is being decided.
Who calls it
The desk has three kinds of visitor.
| Caller | Who they are | How they get a badge |
|---|---|---|
| Your directory's users | People who sign in to your workspace's own directory, such as the users of a custom app; they may have no OpenX account | Sign in once to your directory; the refresh pass keeps them signed in |
| Jobs | Your workspace's automated jobs | Exchange the job's own directory token; a job's badge lives as long as the job's own setting asks for, capped at 60 minutes |
| OpenX users | Everyone who signs in with an OpenX account, customers and Fathym alike | OpenX vouches for them through the relay |
How a vouch works. An OpenX user (or the AI tool acting for them) asks OpenX for a badge. OpenX reads, on its own servers, what that person holds in your workspace, and signs a vouch that is good once, for 5 minutes, for one workspace and one requester. The vouch rides the relay into your environment, to the token service and nowhere else. The token service keeps its own copy of your workspace's members and what they hold, which OpenX pushes over the relay whenever access changes. The badge gets only the rights the vouch and that copy both agree on, so even a forged vouch could not grant more than your workspace's own copy allows. The exact fields of a vouch are being decided.
Personal Access Tokens are made on API Manager's Personal Access Tokens page and start with ftm_pat_. A script
shows one to the token service and gets a badge back, judged again each time against the current member copy and the
revoke list. Personal Access Tokens made with an OpenX account follow the vouch. Making one as a directory user waits
on what the refresh check reads for directory users, which is being decided.
The sign-in modes
Your workspace chooses who can sign in:
- OpenX accounts: people sign in with OpenX.
- Your directory: people sign in to your workspace's own directory.
- Both: either.
Every workspace whose API runs in its own environment gets a token service, whatever its mode, because any OpenX user can make Personal Access Tokens. Which of the three callers each mode lets through at your workspace's API, and whether a vouch is accepted in "Your directory", are being decided.
Ending sign-ins
Anyone can end their own sign-ins and tokens. Access managers, the people with the right to manage the workspace's access, can end other people's. Ending a sign-in removes no card or right; it only stops the badges and passes already handed out.
When access changes in OpenX, the change reaches the token service at once while the relay is connected. Badges already out end on their own (within 5 minutes, or up to 60 for a job's badge), and the revoke list covers anything that lives longer. What a runtime does when it cannot read the revoke list is being decided.
When the relay is off, OpenX cannot vouch, so OpenX users get no new badges until it is back. Your directory's users and your jobs keep working. A Personal Access Token made with an OpenX account keeps working for up to 2 hours on the last member copy, then stops until the relay is back.
Being decided
The points this page states plainly (the 5-minute badge, the 60-minute cap on a job's badge, access managers ending other people's sign-ins, the key starting in a standard Key Vault) are settled. These are still open, and those that come up above are marked being decided:
- The names of the settings in App Identity, and the names written into a badge.
- Where the token service keeps its records, and which of its addresses are reachable from outside your environment.
- How often the signing key rotates, and what happens to the old key.
- Whether a browser or desktop sign-in must also prove its device when it renews.
- Who may ask the service whether a badge is still good.
- What "rights re-checked at each renewal" reads for a directory user, and so when directory users can make Personal Access Tokens.
- Where a workspace with no cloud sees the service's status.
- The exact shape of a vouch and of the member copy, and how the copy is kept up to date.
- Which callers each sign-in mode admits, and whether a runtime accepts a token straight from your directory.
- What a runtime does when the revoke list cannot be read.
On fathym.com: OpenX →