{ "openapi": "3.0.0", "paths": { "/api/namespaces": { "get": { "operationId": "ApiController_listNamespaces", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNamespacesResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List namespaces", "tags": [ "Api", "Namespaces" ] } }, "/api/emails/{namespace}/inbox": { "get": { "description": "This endpoint returns the latest emails from a specific namespace's inbox.\nWhen the `wait` query flag is set to `true` and no emails are found yet, the endpoint waits briefly and redirects back to the same URL so the client can retry the same request automatically.", "operationId": "ApiController_searchInbox", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "description": "The maximum number of emails that can be returned in this request. Must be between 1 and 20", "schema": { "minimum": 1, "maximum": 20, "default": 10, "example": 10, "type": "number" } }, { "name": "offset", "required": true, "in": "query", "description": "The number of emails to skip/ignore, useful for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "from_timestamp", "required": false, "in": "query", "description": "Filter emails by starting unix timestamp in seconds", "schema": { "minimum": 0, "example": 1714857600, "type": "number" } }, { "name": "to_timestamp", "required": false, "in": "query", "description": "Filter emails by ending unix timestamp in seconds", "schema": { "minimum": 0, "example": 1714857600, "type": "number" } }, { "name": "to_addr_prefix", "required": false, "in": "query", "description": "Filter emails by 'to' address. Address must start with this. Example: 'foo' would return for 'foobar@...' but not 'barfoo@...'", "schema": { "example": "john@example.com", "type": "string" } }, { "name": "from_addr_includes", "required": false, "in": "query", "description": "Filter emails by 'from' address. Address must contain this. Example: 'foo' would return for 'foobar@...' but not 'barfoo@...'", "schema": { "example": "john@example.com", "type": "string" } }, { "name": "subject_includes", "required": false, "in": "query", "description": "Filter emails by subject. This is case insensitive. Subject must include this. Example: 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'", "schema": { "example": "example", "type": "string" } }, { "name": "wait", "required": false, "in": "query", "description": "If this flag is true then the request will keep waiting till at least one response is returned", "schema": { "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInboxResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Search inbox", "tags": [ "Api", "Emails" ] } }, "/api/emails/{namespace}/{emailId}/deliverability-report": { "post": { "operationId": "ApiController_requestDeliverabilityReport", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "emailId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "received_timestamp", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverabilityReportResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Generate deliverability report", "tags": [ "Api", "Emails" ] }, "get": { "operationId": "ApiController_getDeliverabilityReport", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "emailId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "received_timestamp", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverabilityReportResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get deliverability report", "tags": [ "Api", "Emails" ] } }, "/api/emails/{namespace}/{emailId}/deliverability-report/raw-source": { "get": { "operationId": "ApiController_getDeliverabilityRawSourceDownload", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "emailId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "received_timestamp", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get raw EML download URL", "tags": [ "Api", "Emails" ] } }, "/api/attachments/{id}": { "get": { "operationId": "ApiController_getAttachment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Unique identifier of the attachment to retrieve", "schema": { "format": "uuid", "example": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAttachmentResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get email attachment", "tags": [ "Api", "Emails" ] } }, "/api/smtp/{namespace}": { "get": { "operationId": "ApiController_getSmtpSettings", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSmtpSettingsResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get namespace settings", "tags": [ "Api", "Namespaces" ] } }, "/api/namespace/{namespace}/settings": { "post": { "operationId": "ApiController_updateNamespaceSettings", "parameters": [ { "name": "namespace", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNamespaceSettingsDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNamespaceSettingsResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update namespace", "tags": [ "Api", "Namespaces" ] } }, "/api/sms/numbers": { "get": { "operationId": "SmsApiController_listNumbers", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSmsNumbersResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List SMS numbers", "tags": [ "SmsApi", "SMS" ] } }, "/api/sms/{phone_number}/messages": { "get": { "description": "This endpoint returns the latest SMS messages for a specific phone number.\nWhen the `wait` query flag is set to `true` and no messages are found yet, the endpoint waits briefly and redirects back to the same URL so the client can retry the same request automatically.", "operationId": "SmsApiController_searchMessages", "parameters": [ { "name": "phone_number", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "offset", "required": true, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "body", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from_number", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from_date", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "to_date", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "wait", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSmsMessagesResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Search SMS messages", "tags": [ "SmsApi", "SMS" ] } }, "/api/sms/virtual": { "post": { "operationId": "SmsApiController_sendVirtualSms", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendVirtualSmsDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "ApiKey": [] } ], "summary": "Simulate SMS message", "tags": [ "SmsApi", "SMS" ] } }, "/api/devices": { "get": { "description": "The Authenticator (TOTP) API lets you generate one-time passwords and manage virtual 2FA devices for testing authentication systems.", "operationId": "TotpApiController_listDevices", "parameters": [ { "name": "username", "required": false, "in": "query", "description": "Filter devices by username or account label. This is case insensitive and matches partial values.", "schema": { "maxLength": 240, "example": "qa@example.com", "type": "string" } }, { "name": "issuer", "required": false, "in": "query", "description": "Filter devices by issuer. This is case insensitive and matches partial values.", "schema": { "maxLength": 240, "example": "GitHub", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The maximum number of virtual security devices that can be returned in this request.", "schema": { "minimum": 1, "maximum": 100, "default": 100, "example": 100, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "The number of virtual security devices to skip, useful for pagination.", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpDeviceListResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List authenticator devices", "tags": [ "Authenticator (TOTP)" ] }, "post": { "description": "Create a saved virtual 2FA authenticator device from a Base32 shared secret.", "operationId": "TotpApiController_createDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTotpDeviceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpDeviceResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create authenticator device", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/custom": { "post": { "description": "Create a saved virtual 2FA authenticator device with custom TOTP metadata and parameters.", "operationId": "TotpApiController_createCustomDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomTotpDeviceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpDeviceResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create custom authenticator device", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/base32-secret-key": { "post": { "description": "Create a saved virtual 2FA authenticator device from a Base32 secret key.", "operationId": "TotpApiController_createBase32SecretKeyDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBase32SecretKeyTotpDeviceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpDeviceResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create authenticator device from Base32 secret key", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/otpauth-url": { "post": { "description": "Create a saved virtual 2FA authenticator device from an otpauth://totp URL.", "operationId": "TotpApiController_createOtpAuthUrlDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOtpAuthUrlTotpDeviceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpDeviceResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create authenticator device from otpauth URL", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/otp": { "post": { "description": "Generate a current one-time password from a Base32 shared secret without saving a device. Optionally wait for the next TOTP period when the current code is too close to expiry.", "operationId": "TotpApiController_getOtpBySharedSecret", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTotpOtpDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpOtpResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Generate OTP from shared secret", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/{deviceId}/otp": { "get": { "description": "Generate the current one-time password for a saved virtual 2FA authenticator device. Optionally wait for the next TOTP period when the current code is too close to expiry.", "operationId": "TotpApiController_getDeviceOtp", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "min_seconds_until_expire", "required": false, "in": "query", "description": "Minimum number of seconds the generated TOTP code must remain valid. Defaults to 0, which returns the current code immediately.", "schema": { "minimum": 0, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpOtpResponseDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get authenticator device OTP", "tags": [ "Authenticator (TOTP)" ] } }, "/api/devices/{deviceId}": { "delete": { "description": "Permanently delete a saved virtual 2FA authenticator device.", "operationId": "TotpApiController_deleteDevice", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "" } }, "security": [ { "ApiKey": [] } ], "summary": "Delete authenticator device", "tags": [ "Authenticator (TOTP)" ] } } }, "info": { "title": "Mailisk REST API", "description": "REST API for Mailisk", "version": "1.0", "contact": { "name": "Mailisk", "url": "https://mailisk.com", "email": "support@mailisk.com" } }, "tags": [], "servers": [ { "url": "https://api.mailisk.dev" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "ListNamespacesResponseDataDto": { "type": "object", "properties": { "id": { "type": "string" }, "namespace": { "type": "string" }, "shared": { "type": "boolean" }, "shared_organisation_id": { "type": "string" }, "settings": { "type": "object", "properties": { "retention_time": { "type": "number" }, "quota_limit": { "type": "number", "nullable": true }, "capture_raw_email": { "type": "boolean" } }, "required": [ "retention_time", "capture_raw_email" ] } }, "required": [ "id", "namespace", "shared", "settings" ] }, "ListNamespacesResponseDto": { "type": "object", "properties": { "total_count": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListNamespacesResponseDataDto" } } }, "required": [ "total_count", "data" ] }, "SearchInboxResponseOptionsDto": { "type": "object", "properties": { "limit": { "type": "number", "description": "The maximum number of emails that can be returned in this request", "example": 10 }, "offset": { "type": "number", "description": "The number of emails skipped in this response", "example": 0 }, "from_timestamp": { "type": "number", "description": "Applied starting unix timestamp filter in seconds", "example": 1714857600 }, "to_timestamp": { "type": "number", "description": "Applied ending unix timestamp filter in seconds", "example": 1714857600 }, "to_addr_prefix": { "type": "string", "description": "Applied filter for email 'to' address prefix", "example": "john@example.com" }, "from_addr_includes": { "type": "string", "description": "Applied filter for email 'from' address substring", "example": "john@example.com" }, "subject_includes": { "type": "string", "description": "Applied case-insensitive subject filter", "example": "password" }, "wait": { "type": "boolean", "description": "Whether long-poll waiting was enabled for the request", "example": true } }, "required": [ "limit", "offset" ] }, "EmailAddressDto": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address", "example": "john@example.com" }, "name": { "type": "string", "description": "Display name, if one is specified", "example": "John Doe" } }, "required": [ "address" ] }, "EmailAttachmentDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the attachment", "example": "att_123" }, "filename": { "type": "string", "description": "Filename of the attachment", "example": "invoice.pdf" }, "content_type": { "type": "string", "description": "Content type of the attachment", "example": "application/pdf" }, "size": { "type": "number", "description": "Size in bytes of the attachment", "example": 1024 } }, "required": [ "id", "filename", "content_type", "size" ] }, "EmailDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Namespace scoped ID", "example": "email_123" }, "from": { "description": "Sender of email", "allOf": [ { "$ref": "#/components/schemas/EmailAddressDto" } ] }, "to": { "description": "Recipients of email", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } }, "cc": { "description": "Carbon-copied recipients for email message", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } }, "bcc": { "description": "Blind carbon-copied recipients for email message", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } }, "subject": { "type": "string", "description": "Subject of email", "example": "Password reset" }, "html": { "type": "string", "description": "Email content that was sent in HTML format" }, "text": { "type": "string", "description": "Email content that was sent in plain text format" }, "received_date": { "format": "date-time", "type": "string", "description": "The datetime that this email was received", "example": "2026-04-25T08:30:00.000Z" }, "received_timestamp": { "type": "number", "description": "The timestamp that this email was received", "example": 1714857600 }, "expires_timestamp": { "type": "number", "description": "The timestamp when this email will be deleted", "example": 1714944000 }, "spam_score": { "type": "number", "description": "Not supported.", "example": null }, "headers": { "type": "object", "description": "The raw email headers", "additionalProperties": { "type": "string" } }, "attachments": { "description": "Attachments of the email", "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachmentDto" } } }, "required": [ "id", "from", "to", "received_date", "received_timestamp", "expires_timestamp" ] }, "SearchInboxResponseDto": { "type": "object", "properties": { "total_count": { "type": "number", "description": "Total number of emails matching the query", "example": 1 }, "options": { "description": "Normalized query options applied to this response", "allOf": [ { "$ref": "#/components/schemas/SearchInboxResponseOptionsDto" } ] }, "data": { "description": "Emails returned by the inbox search", "type": "array", "items": { "$ref": "#/components/schemas/EmailDto" } } }, "required": [ "total_count", "options", "data" ] }, "DeliverabilityReportResponseDto": { "type": "object", "properties": { "status": { "type": "object" }, "analysis_version": { "type": "string" }, "expires_at": { "type": "string", "nullable": true }, "report": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object" } } }, "required": [ "status", "analysis_version", "expires_at" ] }, "GetAttachmentResponseDataDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the attachment", "example": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019" }, "filename": { "type": "string", "description": "Filename of the attachment", "example": "lorem-ipsum.txt" }, "content_type": { "type": "string", "description": "Content type of the attachment", "example": "text/plain" }, "size": { "type": "number", "description": "Size in bytes of the attachment", "example": 446 }, "expires_at": { "type": "string", "nullable": true, "description": "The datetime when this attachment will be deleted", "example": "2026-04-28T08:24:58.000Z" }, "download_url": { "type": "string", "description": "The URL to the attachment", "example": "https://example.com/attachments/1777112698913_5e0c23bc-dc1c-49f3-8d92-9a0d85527019.txt" } }, "required": [ "id", "filename", "content_type", "size", "expires_at", "download_url" ] }, "GetAttachmentResponseDto": { "type": "object", "properties": { "data": { "description": "Attachment response payload", "allOf": [ { "$ref": "#/components/schemas/GetAttachmentResponseDataDto" } ] } }, "required": [ "data" ] }, "GetSmtpSettingsResponseDataDto": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "host", "port", "username", "password" ] }, "GetSmtpSettingsResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetSmtpSettingsResponseDataDto" } }, "required": [ "data" ] }, "UpdateNamespaceSettingsDto": { "type": "object", "properties": { "retention_time": { "type": "number" }, "quota_limit": { "type": "number", "nullable": true }, "capture_raw_email": { "type": "boolean" } } }, "UpdateNamespaceSettingsResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "namespace": { "type": "string" }, "shared": { "type": "boolean" }, "settings": { "type": "object", "properties": { "retention_time": { "type": "number" }, "quota_limit": { "type": "number", "nullable": true }, "capture_raw_email": { "type": "boolean" } }, "required": [ "retention_time", "capture_raw_email" ] } }, "required": [ "id", "namespace", "shared", "settings" ] }, "SmsNumberResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organisation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "requested", "active", "disabled" ] }, "country": { "type": "string" }, "phone_number": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "is_test_number": { "type": "boolean" } }, "required": [ "id", "organisation_id", "status", "country", "created_at", "updated_at" ] }, "ListSmsNumbersResponseDto": { "type": "object", "properties": { "total_count": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmsNumberResponseDto" } } }, "required": [ "total_count", "data" ] }, "SmsMessageResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "sms_phone_number_id": { "type": "string" }, "body": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "provider_message_id": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] } }, "required": [ "id", "sms_phone_number_id", "body", "from_number", "to_number", "created_at", "direction" ] }, "SearchSmsMessagesResponseDto": { "type": "object", "properties": { "total_count": { "type": "number" }, "options": { "type": "object" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMessageResponseDto" } } }, "required": [ "total_count", "options", "data" ] }, "SendVirtualSmsDto": { "type": "object", "properties": { "from_number": { "type": "string" }, "to_number": { "type": "string" }, "body": { "type": "string" } }, "required": [ "from_number", "to_number", "body" ] }, "TotpDeviceListResponseOptionsDto": { "type": "object", "properties": { "limit": { "type": "number", "description": "The maximum number of virtual security devices returned in this response.", "example": 100 }, "offset": { "type": "number", "description": "The number of virtual security devices skipped in this response.", "example": 0 }, "username": { "type": "string", "description": "Applied username/account-label filter.", "example": "qa@example.com" }, "issuer": { "type": "string", "description": "Applied issuer filter.", "example": "GitHub" } }, "required": [ "limit", "offset" ] }, "TotpDeviceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Saved virtual security device id.", "example": "9b1f6ec0-b90d-4bd8-8dd0-f6b2d5138273" }, "organisation_id": { "type": "string", "format": "uuid", "description": "Organisation id that owns this saved virtual security device.", "example": "7f0a9c32-66b2-4e25-a4cf-1f77db8f7f3b" }, "name": { "type": "string", "description": "Human-readable device name.", "example": "GitHub staging" }, "username": { "type": "string", "nullable": true, "description": "Username or account label associated with this device.", "example": "qa@example.com" }, "issuer": { "type": "string", "nullable": true, "description": "Issuer or application label associated with this device.", "example": "GitHub" }, "digits": { "type": "number", "description": "TOTP code length.", "enum": [ 6, 8 ], "example": 6 }, "period": { "type": "number", "description": "TOTP period in seconds.", "example": 30 }, "algorithm": { "type": "string", "description": "TOTP HMAC algorithm.", "enum": [ "SHA1", "SHA256", "SHA512" ], "example": "SHA1" }, "source": { "type": "string", "description": "Creation source for this saved virtual security device.", "enum": [ "shared_secret", "custom", "base32_secret_key", "otpauth_url" ], "example": "custom" }, "expires_at": { "type": "string", "nullable": true, "description": "ISO timestamp after which this saved virtual security device expires.", "example": "2026-05-19T12:00:00.000Z", "format": "date-time" }, "created_at": { "type": "string", "description": "ISO timestamp when this saved virtual security device was created.", "example": "2026-05-18T12:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "ISO timestamp when this saved virtual security device was last updated.", "example": "2026-05-18T12:00:00.000Z", "format": "date-time" } }, "required": [ "id", "organisation_id", "name", "digits", "period", "algorithm", "source", "created_at", "updated_at" ] }, "TotpDeviceListResponseDto": { "type": "object", "properties": { "total_count": { "type": "number", "description": "Total number of active saved virtual security devices matching the query.", "example": 1 }, "options": { "description": "Normalized query options applied to this response.", "allOf": [ { "$ref": "#/components/schemas/TotpDeviceListResponseOptionsDto" } ] }, "items": { "description": "Saved virtual security devices returned by the list request.", "type": "array", "items": { "$ref": "#/components/schemas/TotpDeviceResponseDto" } } }, "required": [ "total_count", "options", "items" ] }, "CreateTotpDeviceDto": { "type": "object", "properties": { "expires_at": { "type": "string", "description": "Optional ISO timestamp after which this saved virtual security device expires.", "example": "2026-05-19T12:00:00.000Z", "format": "date-time" }, "name": { "type": "string", "maxLength": 120, "description": "Optional human-readable name for the saved virtual security device.", "example": "GitHub staging" }, "shared_secret": { "type": "string", "description": "Base32 shared secret used to generate TOTP codes.", "example": "JBSWY3DPEHPK3PXP" } }, "required": [ "shared_secret" ] }, "CreateCustomTotpDeviceDto": { "type": "object", "properties": { "expires_at": { "type": "string", "description": "Optional ISO timestamp after which this saved virtual security device expires.", "example": "2026-05-19T12:00:00.000Z", "format": "date-time" }, "name": { "type": "string", "maxLength": 120, "description": "Optional human-readable name for the saved virtual security device.", "example": "GitHub staging" }, "username": { "type": "string", "maxLength": 240, "description": "Optional username or account label associated with the TOTP secret.", "example": "qa@example.com" }, "issuer": { "type": "string", "maxLength": 240, "description": "Optional issuer or application label associated with the TOTP secret.", "example": "GitHub" }, "digits": { "type": "number", "enum": [ 6, 8 ], "description": "TOTP code length. Defaults to 6 when omitted.", "example": 6 }, "period": { "type": "number", "minimum": 10, "maximum": 300, "description": "TOTP period in seconds. Defaults to 30 when omitted.", "example": 30 }, "algorithm": { "type": "string", "enum": [ "SHA1", "SHA256", "SHA512" ], "description": "TOTP HMAC algorithm. Defaults to SHA1 when omitted.", "example": "SHA1" }, "secret": { "type": "string", "description": "Base32 shared secret used to generate TOTP codes.", "example": "JBSWY3DPEHPK3PXP" } }, "required": [ "secret" ] }, "CreateBase32SecretKeyTotpDeviceDto": { "type": "object", "properties": { "expires_at": { "type": "string", "description": "Optional ISO timestamp after which this saved virtual security device expires.", "example": "2026-05-19T12:00:00.000Z", "format": "date-time" }, "name": { "type": "string", "maxLength": 120, "description": "Optional human-readable name for the saved virtual security device.", "example": "GitHub staging" }, "username": { "type": "string", "maxLength": 240, "description": "Optional username or account label associated with the TOTP secret.", "example": "qa@example.com" }, "issuer": { "type": "string", "maxLength": 240, "description": "Optional issuer or application label associated with the TOTP secret.", "example": "GitHub" }, "digits": { "type": "number", "enum": [ 6, 8 ], "description": "TOTP code length. Defaults to 6 when omitted.", "example": 6 }, "period": { "type": "number", "minimum": 10, "maximum": 300, "description": "TOTP period in seconds. Defaults to 30 when omitted.", "example": 30 }, "algorithm": { "type": "string", "enum": [ "SHA1", "SHA256", "SHA512" ], "description": "TOTP HMAC algorithm. Defaults to SHA1 when omitted.", "example": "SHA1" }, "base32_secret_key": { "type": "string", "description": "Base32 shared secret key used to generate TOTP codes.", "example": "JBSWY3DPEHPK3PXP" } }, "required": [ "base32_secret_key" ] }, "CreateOtpAuthUrlTotpDeviceDto": { "type": "object", "properties": { "expires_at": { "type": "string", "description": "Optional ISO timestamp after which this saved virtual security device expires.", "example": "2026-05-19T12:00:00.000Z", "format": "date-time" }, "name": { "type": "string", "maxLength": 120, "description": "Optional human-readable name for the saved virtual security device.", "example": "GitHub staging" }, "username": { "type": "string", "maxLength": 240, "description": "Optional username or account label. Used only when missing from the otpauth URL.", "example": "qa@example.com" }, "issuer": { "type": "string", "maxLength": 240, "description": "Optional issuer label. Used only when missing from the otpauth URL.", "example": "GitHub" }, "digits": { "type": "number", "enum": [ 6, 8 ], "description": "TOTP code length. Used only when missing from the otpauth URL.", "example": 6 }, "period": { "type": "number", "minimum": 10, "maximum": 300, "description": "TOTP period in seconds. Used only when missing from the otpauth URL.", "example": 30 }, "algorithm": { "type": "string", "enum": [ "SHA1", "SHA256", "SHA512" ], "description": "TOTP HMAC algorithm. Used only when missing from the otpauth URL.", "example": "SHA1" }, "otp_auth_url": { "type": "string", "description": "otpauth://totp URL containing at least a Base32 secret query parameter.", "example": "otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub" } }, "required": [ "otp_auth_url" ] }, "CreateTotpOtpDto": { "type": "object", "properties": { "shared_secret": { "type": "string", "description": "Base32 shared secret used to generate the current TOTP code without saving a device.", "example": "JBSWY3DPEHPK3PXP" }, "min_seconds_until_expire": { "type": "number", "minimum": 0, "description": "Minimum number of seconds the generated TOTP code must remain valid. Defaults to 0, which returns the current code immediately.", "example": 10 } }, "required": [ "shared_secret" ] }, "TotpOtpResponseDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Current TOTP code.", "example": "123456" }, "expires": { "type": "string", "description": "ISO timestamp when this TOTP code expires.", "example": "2026-05-18T12:00:30.000Z", "format": "date-time" } }, "required": [ "code", "expires" ] } } } }