Require a second factor at sign-in
const url = 'https://example.com/v1/auth/settings';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"secondFactor":{"required":true}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://example.com/v1/auth/settings \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "secondFactor": { "required": true } }'Covers signing in by the deployment’s own ways in (the emailed link, and providers like Google, Microsoft and GitHub). Signing in through the workspace’s own identity provider is exempt: it owns MFA there. A site’s people sign in through the site, which owns their second factor, so the setting doesn’t apply to them. Once required, a session made without a second factor ends at its next request, and signing in to the console with an API token is refused. API keys aren’t covered: keep them to service accounts, and rotate them. From a session, turning it on takes a session made with your own second factor (409 second-factor-enroll-first): it would end yours. Audited. Tenant admins only. Mounted when the deployment keeps second factors (from 0.1.9).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Bodyrequired
Section titled “Request Bodyrequired”Require a second factor at sign-in, or stop requiring one.
object
object
Examplegenerated
{ "secondFactor": { "required": true }}Responses
Section titled “Responses”The settings, after.
The workspace’s sign-in settings.
object
object
Signing in by the deployment’s own ways in takes a second factor. Signing in through the workspace’s own identity provider is exempt: it owns MFA there. A site’s people sign in through the site, which owns their second factor, so the setting doesn’t apply to them. API keys aren’t covered.
People whose key is still kept under the deployment’s previous sign-in secret: each moves to the current one at their next code. Keep the previous secret configured until this is 0.
People whose key opens under neither secret: they need a recovery code, or an admin to remove it.
Examplegenerated
{ "secondFactor": { "required": true, "onPreviousSecret": 1, "unusable": 1 }}Malformed request body.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Not a tenant admin.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Turned on from a session made without a second factor (second-factor-enroll-first), or an idempotency conflict.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}