Device Lifecycle
A user's first successful login binds their phone to their account. From then on only that phone can complete their location factor, until you replace it or revoke it.
Binding changes what LFA establishes from "a phone in the region" to "this user's phone in the region": presence and possession. Without binding, anyone with the app inside the geofence could complete anyone's location factor. With binding, the factor is pinned to the device the user enrolled.
Each user has one bound device per client.
Enrollment: the first login
Enrollment requires no administration. During a user's first login:
- The app creates a signing key in the phone's secure hardware and has the platform certify it to LFA: Apple App Attest on iOS, hardware key attestation on Android (device enrollment).
- Your token exchange supplies
octet_user_id, and LFA binds the enrolled device to that user. The first device for a user is bound automatically.
Every later login checks that the device is the one bound to this user. As long as the user keeps the same phone, there is nothing further to do.
The step above is the direct path: your OIDC client sends octet_user_id on
the RP-authenticated token exchange. If you integrate through an identity broker
such as Okta, the broker runs a fixed standard token exchange and cannot add
octet_user_id. Instead, the binding identifier is the login_hint carried
inside the broker's signed authorization request. LFA
verifies that request against the broker's pinned keys, so the device binds to
the authenticated hint, never a raw front-channel value. See
Okta Integration for setup. The rest of this page applies
to both, with the device-replacement difference called out below.
Replacing a phone
If the user still controls their account, let them replace the device themselves. After your own re-verification step (a step-up you trust), send one extra field on the token exchange:
octet_device_enroll=true
LFA revokes the old device and binds the new one, atomically. Without the flag, a
new device claiming an already-bound user is rejected (invalid_grant). That
rejection is what blocks an account-takeover attempt from swapping in an
attacker's phone, so gate the flag behind real verification, not a self-serve
checkbox.
octet_device_enroll is sent on the direct token exchange, and brokers cannot
add fields to it, so enrollment is forced off for broker clients. When a broker user
gets a new phone, their next login is rejected (invalid_grant) and stays
rejected until you clear the old binding with
POST /v1/device/revoke (below). After
the revoke, the next login binds the new phone automatically, with no flag and
no further action.
A lost or stolen phone
Revoke the binding server-side, immediately. No login flow is required. A direct client calls the endpoint itself with its client secret:
curl -s https://factor.octetproof.com/v1/device/revoke \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d octet_user_id=usr_1234
A successful call returns {"revoked": true, "device_id": "<id>"}. If no active
device is bound to that user, it returns 404 no_device. See the
OIDC reference for every response.
From that moment the revoked phone is denied at proof submission, regardless of
where it is or what it can prove. When the user signs in on a replacement phone,
it binds automatically. A revoked device no longer counts as a live one, so no
octet_device_enroll flag is needed.
For a broker client, ask Octet to revoke the
binding. The endpoint accepts a client secret only, and a broker integration
holds no client secret. Revocation is also the only device-recovery path for a
broker, because brokers cannot send octet_device_enroll. Give Octet the
identifier the device is bound to, which is the login_hint value from the
signed request object. For a direct client, that identifier is your
octet_user_id.
What each rejection means
| Error | Meaning | What to do |
|---|---|---|
invalid_request (octet_user_id is required) |
A direct token exchange omitted the user identifier | Send octet_user_id on every exchange |
invalid_grant (this device is bound to a different user) |
The phone that proved presence belongs to another account | The user must use their own enrolled phone |
invalid_grant (a new device requires enrollment) |
The user already has a bound device and this is a different one | Direct: re-verify the user, then retry with octet_device_enroll=true. Broker: ask Octet to revoke the old binding (POST /v1/device/revoke). The next login then binds the new phone |
Scoping
Each client keeps its own bindings, and the user identifiers you send are never visible to other clients. See Trust & Privacy.
Where to go next
- Quick Start. Where
octet_user_idgoes. - OIDC Reference. The revoke endpoint's full contract.