Draft
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
amircheikh
force-pushed
the
amir/mfa-docs
branch
from
fb60931 to
1727c20
Compare
fainashalts
reviewed
Apr 9, 2026
fainashalts
left a comment
fainashalts
left a comment
There was a problem hiding this comment.
LGTM! Found some minor typos and had some optional feedback but overall really solid docs. Psyched to see it!
|
|
||
| ## Enforcing MFA for end users | ||
|
|
||
| Enforcing MFA for an end-user on a sub-organization can do so using a [delegated access user](/concepts/policies/delegated-access-overview). |
There was a problem hiding this comment.
Suggested change
| Enforcing MFA for an end-user on a sub-organization can do so using a [delegated access user](/concepts/policies/delegated-access-overview). | |
| Enforcing MFA for an end user on a sub-organization can be done using a [delegated access user](/concepts/policies/delegated-access-overview). |
|
|
||
| ## MFA recovery | ||
|
|
||
| If an end user loses access to one of their authentication methods, they may be locked out of activities that require MFA. Because Turnkey cannot write to organizations directly, Turnkey is unable to recover users on their behalf. You must set up a recovery mechanism in advance. |
There was a problem hiding this comment.
Suggested change
| If an end user loses access to one of their authentication methods, they may be locked out of activities that require MFA. Because Turnkey cannot write to organizations directly, Turnkey is unable to recover users on their behalf. You must set up a recovery mechanism in advance. | |
| If an end user loses access to one of their authentication methods, they may be locked out of activities that require MFA. Because Turnkey cannot write to organizations directly, Turnkey is unable to recover users on their behalf. **You must set up a recovery mechanism in advance.** |
| MFA is highly customizable and can be configured to require any combination of supported authentication methods for different activities. | ||
|
|
||
| ## MFA policies | ||
| MFA policies are a unique resource type in Turnkey that allows configuation of authentication requirements, scoped to a specific condition. |
There was a problem hiding this comment.
Suggested change
| MFA policies are a unique resource type in Turnkey that allows configuation of authentication requirements, scoped to a specific condition. | |
| MFA policies are a unique resource type in Turnkey that allows configuration of authentication requirements, scoped to a specific condition. |
| ## MFA policies | ||
| MFA policies are a unique resource type in Turnkey that allows configuation of authentication requirements, scoped to a specific condition. | ||
|
|
||
| MFA policies can be created by parent, or sub-organization users and are tied to the targetted user. |
There was a problem hiding this comment.
Suggested change
| MFA policies can be created by parent, or sub-organization users and are tied to the targetted user. | |
| MFA policies can be created by parent or sub-organization users and are tied to the targeted user. |
| ## MFA policies | ||
| MFA policies are a unique resource type in Turnkey that allows configuation of authentication requirements, scoped to a specific condition. | ||
|
|
||
| MFA policies can be created by parent, or sub-organization users and are tied to the targetted user. |
There was a problem hiding this comment.
Might good to add some context here to orient the reader here. Maybe something like: "MFA policies are typically used by parent organizations to enforce authentication requirements on end users in sub-organizations"
|
|
||
| The `order` field is an integer that determines the evaluation priority when a user has multiple MFA policies. Policies with **lower order values are evaluated first**. | ||
|
|
||
| When a request is made, each MFA policy is checked in order. The first policy whose condition evaluates to `true` determines the authentication requirements for that request. This allows you to create specific policies for sensitive operations with lower order values, and broader catch-all policies with higher order values. |
There was a problem hiding this comment.
I think the first policy matches information needs to be called out more. Callout box, etc. since its pretty critical to setting this up right.
|
|
||
| When a user submits an activity and one of their MFA policies evaluates to `true`, the activity is placed in `ACTIVITY_STATUS_AUTHENTICATORS_NEEDED` status. The activity will not execute until the user proves they have the required authentication methods. | ||
|
|
||
| To satisfy MFA, the user must call the `APPROVE_ACTIVITY` activity, passing in the `fingerprint` of the original activity. The way the user stamps this approval request determines which authentication method is proven. |
There was a problem hiding this comment.
Might be good to add a snippet here with example on how they would call APPROVE_ACTIVITY
|
|
||
| Session profiles are resources created by the parent organization that allow sessions to be issued with limited capabilities. When a session is issued with a session profile, the profile's capability is evaluated on every request made with that session. If the capability evaluates to `false`, the request is denied. | ||
|
|
||
| Session profiles are **immutable** - once created, they cannot be edited or deleted. Make sure the configuration is correct before creating a session profile. |
There was a problem hiding this comment.
Might be good to explain what to do if you create one with the wrong configuration. Can you just create a new one and stop using the old one? What is our suggested approach in that scenario.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Developer-facing docs for MFA and Session Profiles
Thanks!