Logto Verifications API
Endpoints for creating and validating verification records, which can be used in Profile routes.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center Verifications API
description: 'API references for Logto services.
Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
version: Cloud
servers:
- url: https://[tenant_id].logto.app/
description: Logto endpoint address.
security:
- OAuth2:
- all
tags:
- name: Verifications
description: Endpoints for creating and validating verification records, which can be used in Profile routes.
paths:
/api/verifications/password:
post:
operationId: CreateVerificationByPassword
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- password
properties:
password:
type: string
minLength: 1
description: The password of the user.
responses:
'201':
description: The verification record was created successfully.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
- expiresAt
properties:
verificationRecordId:
type: string
expiresAt:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: The password is invalid.
summary: Create a record by password
description: Create a verification record by verifying the password.
/api/verifications/verification-code:
post:
operationId: CreateVerificationByVerificationCode
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- identifier
properties:
identifier:
oneOf:
- type: object
required:
- type
- value
properties:
type:
type: string
format: '"email"'
value:
type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
- type: object
required:
- type
- value
properties:
type:
type: string
format: '"phone"'
value:
type: string
format: regex
pattern: /^\d+$/
description: The identifier (email address or phone number) to send the verification code to.
templateType:
oneOf:
- type: string
format: '"BindMfa"'
- type: string
format: '"UserPermissionValidation"'
description: Optional override for the template type used to send the verification code. If the identifier is new, BindNewIdentifier will be used regardless.
responses:
'201':
description: The verification code has been successfully sent.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
- expiresAt
properties:
verificationRecordId:
type: string
expiresAt:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'501':
description: The connector for sending the verification code is not configured.
summary: Create a record by verification code
description: Create a verification record and send the code to the specified identifier. The code verification can be used to verify the given identifier.
/api/verifications/verification-code/verify:
post:
operationId: VerifyVerificationByVerificationCode
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- identifier
- verificationId
- code
properties:
identifier:
oneOf:
- type: object
required:
- type
- value
properties:
type:
type: string
format: '"email"'
value:
type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
- type: object
required:
- type
- value
properties:
type:
type: string
format: '"phone"'
value:
type: string
format: regex
pattern: /^\d+$/
description: The identifier (email address or phone number) to verify the code against. Must match the identifier used to send the verification code.
verificationId:
type: string
description: The verification ID of the CodeVerification record.
code:
type: string
description: The verification code to be verified.
responses:
'200':
description: The verification code has been successfully verified.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
properties:
verificationRecordId:
type: string
'400':
description: The verification code is invalid or the maximum number of attempts has been exceeded. Check the error message for details.
'401':
description: Unauthorized
'403':
description: Forbidden
'501':
description: The connector for sending the verification code is not configured.
summary: Verify verification code
description: Verify the provided verification code against the identifier. If successful, the verification record will be marked as verified.
/api/verifications/social:
post:
operationId: CreateVerificationBySocial
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- state
- redirectUri
- connectorId
properties:
state:
type: string
description: A random string generated on the client side to prevent CSRF (Cross-Site Request Forgery) attacks.
redirectUri:
type: string
description: The URI to navigate back to after the user is authenticated by the connected social identity provider and has granted access to the connector.
scope:
type: string
description: The custom scopes of the social verification. It can be used to request specific permissions from the social identity provider. If provided, it will override the scope configured in the connector settings.
connectorId:
type: string
description: The Logto connector ID.
responses:
'201':
description: Successfully created the social verification record and returned the authorization URI.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
- authorizationUri
- expiresAt
properties:
verificationRecordId:
type: string
description: The ID of the verification record.
authorizationUri:
type: string
description: The authorization URI to navigate to for authentication and authorization in the connected social identity provider.
expiresAt:
type: string
description: The expiration date and time of the verification record.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The connector specified by connectorId is not found.
'422':
description: The connector specified by connectorId is not a valid social connector.
summary: Create a social verification record
description: Create a social verification record and return the authorization URI.
/api/verifications/social/verify:
post:
operationId: VerifyVerificationBySocial
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- connectorData
- verificationRecordId
properties:
connectorData:
type: object
description: A json object constructed from the url query params returned by the social platform. Typically it contains `code`, `state` and `redirectUri` fields.
verificationRecordId:
type: string
verificationId:
description: The verification ID of the SocialVerification record.
responses:
'200':
description: The social verification record has been successfully verified and the user information has been saved.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
properties:
verificationRecordId:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Verify a social verification record
description: Verify a social verification record by callback connector data, and save the user information to the record.
/api/verifications/web-authn/registration:
post:
operationId: GenerateWebAuthnRegistrationOptions
tags:
- Verifications
parameters: []
responses:
'200':
description: Successfully generated the WebAuthn registration options.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
- registrationOptions
- expiresAt
properties:
verificationRecordId:
type: string
registrationOptions:
type: object
required:
- rp
- user
- challenge
- pubKeyCredParams
properties:
rp:
type: object
required:
- name
properties:
name:
type: string
id:
type: string
user:
type: object
required:
- id
- name
- displayName
properties:
id:
type: string
name:
type: string
displayName:
type: string
challenge:
type: string
pubKeyCredParams:
type: array
items:
type: object
required:
- type
- alg
properties:
type:
type: string
format: '"public-key"'
alg:
type: number
timeout:
type: number
excludeCredentials:
type: array
items:
type: object
required:
- type
- id
properties:
type:
type: string
format: '"public-key"'
id:
type: string
transports:
type: array
items:
type: string
enum:
- usb
- nfc
- ble
- internal
- cable
- hybrid
- smart-card
authenticatorSelection:
type: object
properties:
authenticatorAttachment:
type: string
enum:
- platform
- cross-platform
requireResidentKey:
type: boolean
residentKey:
type: string
enum:
- discouraged
- preferred
- required
userVerification:
type: string
enum:
- required
- preferred
- discouraged
attestation:
type: string
enum:
- none
- indirect
- direct
- enterprise
extensions:
type: object
properties:
appid:
type: string
credProps:
type: boolean
hmacCreateSecret:
type: boolean
expiresAt:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Generate WebAuthn registration options
description: Generate WebAuthn registration options for the user to register a new WebAuthn device.
/api/verifications/web-authn/registration/verify:
post:
operationId: VerifyWebAuthnRegistration
tags:
- Verifications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- verificationRecordId
- payload
properties:
verificationRecordId:
type: string
description: The ID of the verification record.
payload:
type: object
required:
- type
- id
- rawId
- response
- clientExtensionResults
properties:
type:
type: string
format: '"WebAuthn"'
id:
type: string
rawId:
type: string
response:
type: object
required:
- clientDataJSON
- attestationObject
properties:
clientDataJSON:
type: string
attestationObject:
type: string
authenticatorData:
type: string
transports:
type: array
items:
type: string
enum:
- usb
- nfc
- ble
- internal
- cable
- hybrid
- smart-card
publicKeyAlgorithm:
type: number
publicKey:
type: string
authenticatorAttachment:
type: string
enum:
- cross-platform
- platform
clientExtensionResults:
type: object
properties:
appid:
type: boolean
crepProps:
type: object
properties:
rk:
type: boolean
hmacCreateSecret:
type: boolean
description: The payload of the WebAuthn device.
responses:
'200':
description: The WebAuthn registration has been successfully verified.
content:
application/json:
schema:
type: object
required:
- verificationRecordId
properties:
verificationRecordId:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Verify WebAuthn registration
description: Verify the WebAuthn registration by the user's response.
components:
securitySchemes:
OAuth2:
type: oauth2
description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[app-id]' \\\n --data-urlencode 'client_secret=[app-secret]' \\\n --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n \"expires_in\": 3600, // Token expiration in seconds\n \"token_type\": \"Bearer\", // Token type for your request when using the access token\n \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n --request GET 'https://[tenant-id].logto.app/api/users' \\\n --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier."
flows:
clientCredentials:
tokenUrl: /oidc/token
scopes:
all: All scopes