{ "components" : { "schemas" : { "AccessPassResponse" : { "properties" : { "accessPass" : { "type" : "string" }, "expiresAt" : { "format" : "date-time", "type" : "string" } }, "required" : [ "accessPass", "expiresAt" ], "type" : "object" }, "ChallengeResponse" : { "properties" : { "approvedWith" : { "enum" : [ "FACTOR", "RECOVERY_CODE", "ACCESS_PASS" ], "type" : [ "string", "null" ] }, "attemptsRemaining" : { "format" : "int32", "type" : "integer" }, "completedAt" : { "format" : "date-time", "type" : [ "string", "null" ] }, "createdAt" : { "format" : "date-time", "type" : "string" }, "deniedReason" : { "enum" : [ "NOT_ME" ], "type" : [ "string", "null" ] }, "email" : { "oneOf" : [ { "$ref" : "#/components/schemas/EmailCodeDetails" }, { "type" : "null" } ] }, "expiresAt" : { "format" : "date-time", "type" : "string" }, "factorId" : { "format" : "uuid", "type" : "string" }, "id" : { "format" : "uuid", "type" : "string" }, "push" : { "oneOf" : [ { "$ref" : "#/components/schemas/PushChallengeDetails" }, { "type" : "null" } ] }, "status" : { "enum" : [ "PENDING", "APPROVED", "DENIED", "FAILED", "EXPIRED" ], "type" : "string" }, "userId" : { "format" : "uuid", "type" : "string" } }, "required" : [ "attemptsRemaining", "createdAt", "expiresAt", "factorId", "id", "status", "userId" ], "type" : "object" }, "CheckDeviceRequest" : { "properties" : { "token" : { "maxLength" : 200, "minLength" : 0, "type" : "string" } }, "required" : [ "token" ], "type" : "object" }, "CheckDeviceResponse" : { "properties" : { "expiresAt" : { "format" : "date-time", "type" : [ "string", "null" ] }, "trusted" : { "type" : "boolean" } }, "required" : [ "trusted" ], "type" : "object" }, "CreateChallengeRequest" : { "properties" : { "context" : { "oneOf" : [ { "$ref" : "#/components/schemas/SignInContext" }, { "type" : "null" } ] }, "factorId" : { "format" : "uuid", "type" : "string" }, "language" : { "pattern" : "ja|en", "type" : [ "string", "null" ] }, "userId" : { "format" : "uuid", "type" : "string" } }, "required" : [ "factorId", "userId" ], "type" : "object" }, "CreateUserRequest" : { "properties" : { "displayName" : { "maxLength" : 255, "minLength" : 0, "type" : [ "string", "null" ] }, "externalId" : { "maxLength" : 255, "minLength" : 0, "type" : "string" } }, "required" : [ "externalId" ], "type" : "object" }, "EmailCodeDetails" : { "properties" : { "expiresAt" : { "format" : "date-time", "type" : "string" }, "sentTo" : { "type" : "string" } }, "required" : [ "expiresAt", "sentTo" ], "type" : "object" }, "EmailMethod" : { "properties" : { "allowed" : { "type" : "boolean" }, "domains" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "allowed", "domains" ], "type" : "object" }, "EnrollFactorRequest" : { "properties" : { "email" : { "maxLength" : 254, "minLength" : 0, "type" : [ "string", "null" ] }, "label" : { "maxLength" : 100, "minLength" : 0, "type" : [ "string", "null" ] }, "language" : { "pattern" : "ja|en", "type" : [ "string", "null" ] }, "type" : { "enum" : [ "TOTP", "PUSH", "EMAIL" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "EnrollmentResponse" : { "properties" : { "email" : { "oneOf" : [ { "$ref" : "#/components/schemas/EmailCodeDetails" }, { "type" : "null" } ] }, "factor" : { "$ref" : "#/components/schemas/FactorResponse" }, "push" : { "oneOf" : [ { "$ref" : "#/components/schemas/PushEnrollmentDetails" }, { "type" : "null" } ] }, "totp" : { "oneOf" : [ { "$ref" : "#/components/schemas/TotpEnrollmentDetails" }, { "type" : "null" } ] } }, "required" : [ "factor" ], "type" : "object" }, "FactorResponse" : { "properties" : { "activatedAt" : { "format" : "date-time", "type" : [ "string", "null" ] }, "createdAt" : { "format" : "date-time", "type" : "string" }, "emailHint" : { "type" : [ "string", "null" ] }, "id" : { "format" : "uuid", "type" : "string" }, "label" : { "type" : [ "string", "null" ] }, "status" : { "enum" : [ "PENDING", "ACTIVE", "DELETED" ], "type" : "string" }, "type" : { "enum" : [ "TOTP", "PUSH", "EMAIL" ], "type" : "string" } }, "required" : [ "createdAt", "id", "status", "type" ], "type" : "object" }, "IssueAccessPassRequest" : { "properties" : { "issuedBy" : { "maxLength" : 100, "minLength" : 0, "type" : [ "string", "null" ] } }, "type" : "object" }, "MethodsResponse" : { "properties" : { "email" : { "$ref" : "#/components/schemas/EmailMethod" }, "push" : { "type" : "boolean" }, "totp" : { "type" : "boolean" } }, "required" : [ "email", "push", "totp" ], "type" : "object" }, "Problem" : { "description" : "An error (RFC 9457 problem details). Tell errors apart by `code`, never by the text.", "properties" : { "challengeId" : { "description" : "email_unavailable at sign-in: still open for a recovery code", "format" : "uuid", "type" : "string" }, "claimed" : { "description" : "organization_exists: whether its Administrator has signed in", "type" : "boolean" }, "clientIp" : { "description" : "ip_not_allowed", "type" : "string" }, "code" : { "description" : "Stable, for programs", "enum" : [ "invalid_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "request_too_large", "invalid_email", "email_required", "invalid_ip_address", "invalid_username", "invalid_display_name", "wrong_factor_type", "factor_not_pending", "factor_not_active", "enrollment_expired", "challenge_not_pending", "challenge_not_approved", "challenge_too_old", "challenge_already_used", "no_active_factor", "email_codes_not_allowed", "email_domain_not_allowed", "organization_exists", "organization_claimed", "username_taken", "platform_key_exists", "invalid_code", "factor_locked", "too_many_requests", "ip_not_allowed", "push_not_configured", "email_unavailable" ], "type" : "string" }, "detail" : { "description" : "For people; may change", "type" : "string" }, "errors" : { "description" : "invalid_request: the refused fields", "items" : { "properties" : { "field" : { "type" : "string" }, "message" : { "type" : "string" } }, "type" : "object" }, "type" : "array" }, "instance" : { "type" : "string" }, "lockedUntil" : { "description" : "factor_locked", "format" : "date-time", "type" : "string" }, "organizationId" : { "description" : "organization_exists", "format" : "uuid", "type" : "string" }, "retryAfter" : { "description" : "too_many_requests", "format" : "date-time", "type" : "string" }, "status" : { "format" : "int32", "type" : "integer" }, "title" : { "type" : "string" }, "type" : { "format" : "uri", "type" : "string" } }, "required" : [ "code", "status" ], "type" : "object" }, "PushChallengeDetails" : { "properties" : { "number" : { "format" : "int32", "type" : "integer" } }, "required" : [ "number" ], "type" : "object" }, "PushEnrollmentDetails" : { "properties" : { "activationNumber" : { "format" : "int32", "type" : "integer" }, "enrollmentUri" : { "type" : "string" }, "expiresAt" : { "format" : "date-time", "type" : "string" }, "qrCode" : { "type" : "string" } }, "required" : [ "activationNumber", "enrollmentUri", "expiresAt", "qrCode" ], "type" : "object" }, "RecoverChallengeRequest" : { "properties" : { "code" : { "maxLength" : 64, "minLength" : 0, "type" : "string" } }, "required" : [ "code" ], "type" : "object" }, "RecoverChallengeResponse" : { "properties" : { "challenge" : { "$ref" : "#/components/schemas/ChallengeResponse" }, "recoveryCodesRemaining" : { "format" : "int32", "type" : "integer" }, "verified" : { "type" : "boolean" } }, "required" : [ "challenge", "recoveryCodesRemaining", "verified" ], "type" : "object" }, "RecoveryCodesResponse" : { "properties" : { "codes" : { "items" : { "type" : "string" }, "type" : "array" }, "createdAt" : { "format" : "date-time", "type" : "string" } }, "required" : [ "codes", "createdAt" ], "type" : "object" }, "RecoveryStatusResponse" : { "properties" : { "createdAt" : { "format" : "date-time", "type" : [ "string", "null" ] }, "remaining" : { "format" : "int32", "type" : "integer" } }, "required" : [ "remaining" ], "type" : "object" }, "RememberDeviceRequest" : { "properties" : { "challengeId" : { "format" : "uuid", "type" : "string" } }, "required" : [ "challengeId" ], "type" : "object" }, "RememberDeviceResponse" : { "properties" : { "expiresAt" : { "format" : "date-time", "type" : "string" }, "id" : { "format" : "uuid", "type" : "string" }, "token" : { "type" : "string" } }, "required" : [ "expiresAt", "id", "token" ], "type" : "object" }, "SignInContext" : { "properties" : { "ipAddress" : { "maxLength" : 45, "minLength" : 0, "type" : [ "string", "null" ] }, "userAgent" : { "maxLength" : 512, "minLength" : 0, "type" : [ "string", "null" ] } }, "type" : "object" }, "TotpEnrollmentDetails" : { "properties" : { "otpauthUri" : { "type" : "string" }, "qrCode" : { "type" : "string" }, "secret" : { "type" : "string" } }, "required" : [ "otpauthUri", "qrCode", "secret" ], "type" : "object" }, "UpdateUserRequest" : { "properties" : { "displayName" : { "maxLength" : 255, "minLength" : 0, "type" : [ "string", "null" ] } }, "type" : "object" }, "UserResponse" : { "properties" : { "createdAt" : { "format" : "date-time", "type" : "string" }, "displayName" : { "type" : [ "string", "null" ] }, "externalId" : { "type" : "string" }, "id" : { "format" : "uuid", "type" : "string" } }, "required" : [ "createdAt", "externalId", "id" ], "type" : "object" }, "VerifyChallengeResponse" : { "properties" : { "challenge" : { "$ref" : "#/components/schemas/ChallengeResponse" }, "verified" : { "type" : "boolean" } }, "required" : [ "challenge", "verified" ], "type" : "object" }, "VerifyCodeRequest" : { "properties" : { "code" : { "pattern" : "\\d{6}", "type" : "string" } }, "required" : [ "code" ], "type" : "object" } }, "securitySchemes" : { "bearer" : { "description" : "Application API key (tnk_...) for /v1, platform key (tnp_...) for /platform, or the admin token for /admin", "scheme" : "bearer", "type" : "http" }, "device" : { "description" : "Tenon Authenticator only: ECDSA P-256 signature with the Tenon-Factor and Tenon-Timestamp headers", "in" : "header", "name" : "Tenon-Signature", "type" : "apiKey" } } }, "info" : { "description" : "Multi-factor authentication for your application: set up a second step for your users, and check it at sign-in. Every error is a problem detail (RFC 9457) with a stable `code`.", "title" : "Tenon-Auth API", "version" : "v1" }, "openapi" : "3.1.0", "paths" : { "/v1/challenges" : { "post" : { "operationId" : "createChallenge", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateChallengeRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChallengeResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields; `invalid_ip_address`: The sign-in context's IP address is not an IPv4 or IPv6 address" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`factor_not_active`: The method is not active (not set up yet, or removed)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`too_many_requests`: Too many requests or emails in a short time; try again after `retryAfter`; `factor_locked`: Too many wrong codes: the method is locked until `lockedUntil`" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`email_unavailable`: No email could be sent. At sign-in, `challengeId` is still open for a recovery code" } }, "summary" : "Start a sign-in's second step (sends the approval request or the email)", "tags" : [ "Sign-in" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "factor_not_active", "invalid_ip_address", "too_many_requests", "factor_locked", "email_unavailable" ] } }, "/v1/challenges/{challengeId}" : { "get" : { "operationId" : "getChallenge", "parameters" : [ { "in" : "path", "name" : "challengeId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChallengeResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "A sign-in request and its status; poll it while waiting for approval", "tags" : [ "Sign-in" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] } }, "/v1/challenges/{challengeId}/recover" : { "post" : { "operationId" : "recoverChallenge", "parameters" : [ { "in" : "path", "name" : "challengeId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RecoverChallengeRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RecoverChallengeResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`challenge_not_pending`: The sign-in request is already approved, denied, failed or expired; `factor_not_active`: The method is not active (not set up yet, or removed)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`factor_locked`: Too many wrong codes: the method is locked until `lockedUntil`" } }, "summary" : "Pass the second step with a recovery code or an access pass", "tags" : [ "Sign-in" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "challenge_not_pending", "factor_not_active", "factor_locked" ] } }, "/v1/challenges/{challengeId}/verify" : { "post" : { "operationId" : "verifyChallenge", "parameters" : [ { "in" : "path", "name" : "challengeId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/VerifyCodeRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/VerifyChallengeResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`challenge_not_pending`: The sign-in request is already approved, denied, failed or expired; `factor_not_active`: The method is not active (not set up yet, or removed); `wrong_factor_type`: This method can't do that (e.g. a code for sign-in approval)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`factor_locked`: Too many wrong codes: the method is locked until `lockedUntil`" } }, "summary" : "Check a code the user typed", "tags" : [ "Sign-in" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "challenge_not_pending", "factor_not_active", "wrong_factor_type", "factor_locked" ] } }, "/v1/methods" : { "get" : { "operationId" : "getMethods", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MethodsResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Which methods the organization offers", "tags" : [ "Methods" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large" ] } }, "/v1/users" : { "get" : { "operationId" : "findUser", "parameters" : [ { "in" : "query", "name" : "externalId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UserResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Find a user by external ID, without creating one", "tags" : [ "Users" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] }, "post" : { "operationId" : "createUser", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateUserRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UserResponse" } } }, "description" : "A user with this external ID exists already: that user" }, "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UserResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Create a user, or get the existing one with this external ID", "tags" : [ "Users" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large" ] } }, "/v1/users/{userId}" : { "delete" : { "operationId" : "deleteUser", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Delete a user and everything Tenon-Auth keeps about them", "tags" : [ "Users" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] }, "get" : { "operationId" : "getUser", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UserResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Get a user", "tags" : [ "Users" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] }, "patch" : { "operationId" : "updateUser", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateUserRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UserResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Change the name shown in authenticator apps", "tags" : [ "Users" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] } }, "/v1/users/{userId}/access-passes" : { "post" : { "operationId" : "createAccessPass", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IssueAccessPassRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AccessPassResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`no_active_factor`: The user has no active method, so there is nothing to recover" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Issue a one-time access pass (helpdesk, after checking who is asking)", "tags" : [ "Recovery" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "no_active_factor" ] } }, "/v1/users/{userId}/factors" : { "get" : { "operationId" : "listFactors", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/FactorResponse" }, "type" : "array" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "A user's methods", "tags" : [ "Methods" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] }, "post" : { "operationId" : "createFactor", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnrollFactorRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnrollmentResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields; `email_required`: Email codes need an email address; `invalid_email`: Not an email address" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`email_codes_not_allowed`: The organization's Administrator does not allow email codes; `email_domain_not_allowed`: The address's domain is not one the organization allows" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`too_many_requests`: Too many requests or emails in a short time; try again after `retryAfter`" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`push_not_configured`: Sign-in approval is not set up on this server; `email_unavailable`: No email could be sent. At sign-in, `challengeId` is still open for a recovery code" } }, "summary" : "Start setting up a method: authenticator codes (TOTP), sign-in approval (PUSH) or email codes (EMAIL)", "tags" : [ "Methods" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "push_not_configured", "email_required", "invalid_email", "email_codes_not_allowed", "email_domain_not_allowed", "email_unavailable", "too_many_requests" ] } }, "/v1/users/{userId}/factors/{factorId}" : { "delete" : { "operationId" : "deleteFactor", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "factorId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Remove a method", "tags" : [ "Methods" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] } }, "/v1/users/{userId}/factors/{factorId}/activate" : { "post" : { "operationId" : "activateFactor", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "factorId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/VerifyCodeRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FactorResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`wrong_factor_type`: This method can't do that (e.g. a code for sign-in approval); `factor_not_pending`: The method is already active or was removed; `enrollment_expired`: The setup took too long or had too many wrong codes: start the setup again" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" }, "422" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_code`: The code is wrong" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`factor_locked`: Too many wrong codes: the method is locked until `lockedUntil`" } }, "summary" : "Finish setting up a method with its first code (TOTP, EMAIL)", "tags" : [ "Methods" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "wrong_factor_type", "factor_not_pending", "enrollment_expired", "invalid_code", "factor_locked" ] } }, "/v1/users/{userId}/recovery-codes" : { "get" : { "operationId" : "getRecoveryCodes", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RecoveryStatusResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "How many recovery codes the user has left", "tags" : [ "Recovery" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found" ] }, "post" : { "operationId" : "createRecoveryCodes", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RecoveryCodesResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`no_active_factor`: The user has no active method, so there is nothing to recover" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "New recovery codes, replacing the user's old ones", "tags" : [ "Recovery" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "no_active_factor" ] } }, "/v1/users/{userId}/trusted-devices" : { "post" : { "operationId" : "rememberDevice", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RememberDeviceRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RememberDeviceResponse" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`not_found`: No such user, method or sign-in request in this organization" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`challenge_not_approved`: The sign-in request was not approved; `challenge_too_old`: The sign-in was approved too long ago to remember the device; `challenge_already_used`: A device was already remembered with this sign-in; `factor_not_active`: The method is not active (not set up yet, or removed)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Remember this browser after a sign-in, so it can skip the second step", "tags" : [ "Remembered devices" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large", "not_found", "challenge_not_approved", "challenge_too_old", "challenge_already_used", "factor_not_active" ] } }, "/v1/users/{userId}/trusted-devices/check" : { "post" : { "operationId" : "checkDevice", "parameters" : [ { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CheckDeviceRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CheckDeviceResponse" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`invalid_request`: The request is malformed or a field is invalid; `errors` lists the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`unauthorized`: No valid credential: the API key is missing, wrong or revoked" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`forbidden`: The credential is valid but may not use this address" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "`request_too_large`: The request body is larger than 64 KB" } }, "summary" : "Whether a remembered browser may skip the second step", "tags" : [ "Remembered devices" ], "x-error-codes" : [ "invalid_request", "unauthorized", "forbidden", "request_too_large" ] } } }, "security" : [ { "bearer" : [ ] } ], "servers" : [ { "description" : "Tenon-Auth", "url" : "https://api.glow-kin.com" } ] }