Factors

The caller’s own second factors: whether two-factor authentication is on, and each authenticator

GET /v1/factors · operation listFactors

Requires the batondeck:workspace:read permission (action factor:list).

Responses

Status	Meaning
200	The caller’s own second factors: whether two-factor authentication is on, and each authenticator
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "factors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "created_at"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "enabled",
    "factors"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/factors' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Start adding an authenticator app: the QR code and secret, shown once, and the enrolment its first code finishes. Nothing changes until then

POST /v1/factors · operation startFactorEnrolment

Requires the batondeck:workspace:read permission (action factor:enroll).

Requires a step-up: MFA enrolled and re-authenticated within 15 minutes. Not reachable with an API key — a key has no session and so can never step up.

Refused while the workspace is suspended or on deletion hold.

Responses

Status	Meaning
201	Start adding an authenticator app: the QR code and secret, shown once, and the enrolment its first code finishes. Nothing changes until then
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "enrolment": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    },
    "uri": {
      "type": "string"
    },
    "qr_code": {
      "type": "string"
    },
    "expires_at": {
      "type": "number"
    }
  },
  "required": [
    "enrolment",
    "secret",
    "uri",
    "qr_code",
    "expires_at"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/factors' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Finish adding an authenticator with the code it shows: from then on, signing in asks for it

POST /v1/factors/verify · operation verifyFactorEnrolment

Requires the batondeck:workspace:read permission (action factor:enroll).

Requires a step-up: MFA enrolled and re-authenticated within 15 minutes. Not reachable with an API key — a key has no session and so can never step up.

Refused while the workspace is suspended or on deletion hold.

Request body (application/json)

Field	Type	Required	Notes
enrolment	string	yes	≥ 1 chars, ≤ 2048 chars
code	string	yes

Request schema

{
  "type": "object",
  "properties": {
    "enrolment": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "code": {
      "type": "string",
      "pattern": "^\\d{6}$"
    }
  },
  "required": [
    "enrolment",
    "code"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
201	Finish adding an authenticator with the code it shows: from then on, signing in asks for it
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "factor": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "created_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "factor"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/factors/verify' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Remove one of the caller’s authenticators; with none left, signing in asks for no code

DELETE /v1/factors/{id} · operation removeFactor

Requires the batondeck:workspace:read permission (action factor:remove).

Requires a step-up: MFA enrolled and re-authenticated within 15 minutes. Not reachable with an API key — a key has no session and so can never step up.

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
id	path	string	yes

Responses

Status	Meaning
204	Done. No body.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

curl -X DELETE 'https://api.batondeck.com/v1/factors/:id' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"