Passbolt Multi-Factor Authentication API
Complete and validate authentication for users with MFA enabled.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/passbolt-multi-factor-authentication-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: contact@passbolt.com
description: This is a low-level overview of the API and its endpoints, if you need higher-level guides for interacting with the endpoints, use the Developer guide.
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
termsOfService: https://www.passbolt.com/terms
title: Passbolt Authentication (GPGAuth) Authentication (GPGAuth) Multi-Factor Authentication API
version: 5.0.0
servers:
- url: https://passbolt.local
description: API Passbolt
tags:
- name: Multi-Factor Authentication
description: 'Complete and validate authentication for users with MFA enabled.
'
paths:
/mfa/verify/{mfaProviderName}.json:
get:
summary: Check multi-factor authentication.
operationId: mfaVerifyCheck
description: 'Check if MFA validation is needed. `400` means that this kind of MFA is not required.
'
security:
- bearerHttpAuthentication: []
x-codeSamples:
- lang: cURL
source: "curl --request GET \\\n --url {{API_BASE_URL}}/mfa/verify/totp.json \\\n --header 'Authorization: Bearer {{JWT_TOKEN}}'\n"
- lang: JavaScript
source: "const url = '{{API_BASE_URL}}/mfa/verify/totp.json';\nconst options = {method: 'GET', headers: {Authorization: 'Bearer {{JWT_TOKEN}}'}};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n"
- lang: PHP
source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{API_BASE_URL}}/mfa/verify/totp.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n"
tags:
- Multi-Factor Authentication
parameters:
- $ref: '#/components/parameters/mfaProviderName'
responses:
'200':
$ref: '#/components/responses/nullBody'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/authenticationRequired'
post:
summary: Attempt multi-factor authentication.
operationId: mfaVerifyAttempt
security:
- bearerHttpAuthentication: []
x-codeSamples:
- lang: cURL
source: "curl --request POST \\\n --url {{API_BASE_URL}}/mfa/verify/totp.json \\\n --header 'Authorization: Bearer {{JWT_TOKEN}}' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"totp\": \"654373\"\n }'\n"
- lang: JavaScript
source: "const url = '{{API_BASE_URL}}/mfa/verify/totp.json';\nconst options = {\n method: 'POST',\n headers: {Authorization: 'Bearer {{JWT_TOKEN}}'},\n body: '{\"totp\":\"654373\"}'\n};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n"
- lang: PHP
source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{API_BASE_URL}}/mfa/verify/totp.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => json_encode([\n 'totp' => '654373'\n ]),\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n"
tags:
- Multi-Factor Authentication
requestBody:
$ref: '#/components/requestBodies/attempt'
parameters:
- $ref: '#/components/parameters/mfaProviderName'
responses:
'200':
$ref: '#/components/responses/nullBody'
'400':
$ref: '#/components/responses/invalidOtp'
'401':
$ref: '#/components/responses/authenticationRequired'
/mfa/verify/error.json:
get:
summary: Information about MFA requirements.
operationId: mfaVerifyError
security:
- bearerHttpAuthentication: []
x-codeSamples:
- lang: cURL
source: "curl --request GET \\\n --url {{API_BASE_URL}}/mfa/verify/error.json \\\n --header 'Authorization: Bearer {{JWT_TOKEN}}'\n"
- lang: JavaScript
source: "const url = '{{API_BASE_URL}}/mfa/verify/error.json';\nconst options = {method: 'GET', headers: {Authorization: 'Bearer {{JWT_TOKEN}}'}};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n"
- lang: PHP
source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{API_BASE_URL}}/mfa/verify/error.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n"
tags:
- Multi-Factor Authentication
responses:
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/authenticationRequired'
'403':
$ref: '#/components/responses/error'
components:
responses:
badRequest:
description: Bad request
content:
application/json:
schema:
type: object
required:
- header
- body
properties:
header:
$ref: '#/components/schemas/header'
body:
type: string
examples:
example:
value:
header:
id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
status: error
servertime: 1721207029
action: 4d0c0996-ce30-4bce-9918-9062ab35c542
message: <ERROR MESSAGE>
url: <API ENDPOINT URL>
code: 400
body: ''
authenticationRequired:
description: Authentication required.
content:
application/json:
schema:
type: object
required:
- header
- body
properties:
header:
$ref: '#/components/schemas/header'
body:
type: string
examples:
base:
value:
header:
id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a
status: error
servertime: 1721727753
action: e2aa01a9-84ec-55f8-aaed-24ee23259339
message: Authentication is required to continue.
url: <API ENDPOINT URL>
code: 401
body: ''
nullBody:
description: Operation is successful.
content:
application/json:
schema:
type: object
required:
- header
- body
properties:
header:
$ref: '#/components/schemas/header'
body:
type: 'null'
examples:
base:
value:
header:
id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a
status: success
servertime: 1721727753
action: e2aa01a9-84ec-55f8-aaed-24ee23259339
message: <SUCCESS MESSAGE>
url: <API ENDPOINT URL>
code: 200
body: null
invalidOtp:
description: Invalid OTP code.
content:
application/json:
schema:
type: object
required:
- header
- body
properties:
header:
$ref: '#/components/schemas/header'
body:
$ref: '#/components/schemas/invalidOtp'
examples:
base:
value:
header:
id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
status: error
servertime: 1721207029
action: 4d0c0996-ce30-4bce-9918-9062ab35c542
message: Something went wrong when validating the one-time password.
url: /mfa/verify/totp.json
code: 400
body:
totp:
isValidOtp: This OTP is not valid.
error:
description: MFA is required.
content:
application/json:
schema:
type: object
required:
- header
- body
properties:
header:
$ref: '#/components/schemas/header'
body:
$ref: '#/components/schemas/error'
examples:
base:
value:
header:
id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
status: error
servertime: 1721207029
action: 4d0c0996-ce30-4bce-9918-9062ab35c542
message: MFA authentication is required.
url: /mfa/verify/error.json
code: 403
body:
mfa_providers:
- totp
schemas:
invalidOtp:
anyOf:
- type: object
required:
- totp
properties:
totp:
type: object
properties:
numeric:
type: string
minLength:
type: string
isValidOtp:
type: string
- type: object
required:
- hotp
properties:
hotp:
type: object
properties:
isValidModhex:
type: string
isValidHotp:
type: string
header:
type: object
required:
- id
- status
- servertime
- action
- message
- url
- code
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- success
- error
servertime:
type: integer
example: 1720702619
action:
type: string
format: uuid
message:
type: string
example: The operation was successful.
url:
type: string
format: uri
example: /auth/verify.json
code:
type: integer
example: 200
error:
type: object
required:
- mfa_providers
properties:
mfa_providers:
type: array
items:
type: string
enum:
- totp
- yubikey
mfaAttempt:
anyOf:
- type: object
required:
- totp
properties:
totp:
type: string
description: One-time code for TOTP-based MFA.
remember:
type: integer
enum:
- 0
- 1
- type: object
required:
- hotp
properties:
hotp:
type: string
description: One-time code for Yubikey-based MFA.
remember:
type: integer
enum:
- 0
- 1
requestBodies:
attempt:
description: The code for the MFA attempt.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/mfaAttempt'
examples:
totp:
summary: Attempt MFA with TOTP.
value:
totp: '635742'
parameters:
mfaProviderName:
name: mfaProviderName
description: Name for the MFA provider.
in: path
schema:
type: string
enum:
- totp
- yubikey
securitySchemes:
bearerHttpAuthentication:
description: Bearer token using a JWT
type: http
scheme: Bearer
bearerFormat: JWT
gpgCookieAuthentication:
description: Session-based authentication. Note that a CSRF token needs to be provided through a header named `X-CSRF-Token`.
type: apiKey
in: cookie
name: passbolt_session