Logto One-time tokens API
One-time tokens are used for various authentication and verification purposes. They are typically sent via email and have an expiration time.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center One-time tokens 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: One-time tokens
description: One-time tokens are used for various authentication and verification purposes. They are typically sent via email and have an expiration time.
paths:
/api/one-time-tokens:
get:
operationId: ListOneTimeTokens
tags:
- One-time tokens
parameters:
- name: email
in: query
required: false
schema:
type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
description: Filter one-time tokens by email address.
- name: status
in: query
required: false
schema:
type: string
enum:
- active
- consumed
- revoked
- expired
description: Filter one-time tokens by status.
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of one-time tokens.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- email
- token
- context
- status
- createdAt
- expiresAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
email:
type: string
minLength: 1
maxLength: 128
token:
type: string
minLength: 1
maxLength: 256
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
status:
type: string
enum:
- active
- consumed
- revoked
- expired
createdAt:
type: number
expiresAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get one-time tokens
description: Get a list of one-time tokens, filtering by email and status, with optional pagination.
post:
operationId: AddOneTimeTokens
tags:
- One-time tokens
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
minLength: 1
maxLength: 128
description: The email address to associate with the one-time token.
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
description: Additional context to store with the one-time token. This can be used to store arbitrary data that will be associated with the token.
expiresIn:
type: number
description: The expiration time in seconds. If not provided, defaults to 10 mins (600 seconds).
responses:
'201':
description: The one-time token was created successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- email
- token
- context
- status
- createdAt
- expiresAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
email:
type: string
minLength: 1
maxLength: 128
token:
type: string
minLength: 1
maxLength: 256
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
status:
type: string
enum:
- active
- consumed
- revoked
- expired
createdAt:
type: number
expiresAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Create one-time token
description: Create a new one-time token associated with an email address. The token can be used for verification purposes and has an expiration time.
/api/one-time-tokens/{id}:
get:
operationId: GetOneTimeToken
tags:
- One-time tokens
parameters:
- $ref: '#/components/parameters/oneTimeTokenId-root'
responses:
'200':
description: The one-time token found by ID.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- email
- token
- context
- status
- createdAt
- expiresAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
email:
type: string
minLength: 1
maxLength: 128
token:
type: string
minLength: 1
maxLength: 256
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
status:
type: string
enum:
- active
- consumed
- revoked
- expired
createdAt:
type: number
expiresAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get one-time token by ID
description: Get a one-time token by its ID.
delete:
operationId: DeleteOneTimeToken
tags:
- One-time tokens
parameters:
- $ref: '#/components/parameters/oneTimeTokenId-root'
responses:
'204':
description: The one-time token was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Delete one-time token by ID
description: Delete a one-time token by its ID.
/api/one-time-tokens/verify:
post:
operationId: VerifyOneTimeToken
tags:
- One-time tokens
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- token
- email
properties:
token:
type: string
minLength: 1
maxLength: 256
description: The one-time token to verify.
email:
type: string
minLength: 1
maxLength: 128
description: The email address associated with the one-time token.
responses:
'200':
description: The one-time token was verified successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- email
- token
- context
- status
- createdAt
- expiresAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
email:
type: string
minLength: 1
maxLength: 128
token:
type: string
minLength: 1
maxLength: 256
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
status:
type: string
enum:
- active
- consumed
- revoked
- expired
createdAt:
type: number
expiresAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Verify one-time token
description: Verify a one-time token associated with an email address. If the token is valid and not expired, it will be marked as consumed.
/api/one-time-tokens/{id}/status:
put:
operationId: ReplaceOneTimeTokenStatus
tags:
- One-time tokens
parameters:
- $ref: '#/components/parameters/oneTimeTokenId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
enum:
- active
- consumed
- revoked
- expired
description: The new status of the one-time token.
responses:
'200':
description: The one-time token status was updated successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- email
- token
- context
- status
- createdAt
- expiresAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
email:
type: string
minLength: 1
maxLength: 128
token:
type: string
minLength: 1
maxLength: 256
context:
type: object
properties:
jitOrganizationIds:
type: array
items:
type: string
status:
type: string
enum:
- active
- consumed
- revoked
- expired
createdAt:
type: number
expiresAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update one-time token status
description: Update the status of a one-time token by its ID. This can be used to mark the token as consumed or expired.
components:
parameters:
oneTimeTokenId-root:
in: path
description: The unique identifier of the one time token.
required: true
schema:
type: string
name: id
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