Logto Domains API
Custom domain lets you present a consistent brand by having your own domain name on the sign-in and registration pages. See [🌍 Custom domain](https://docs.logto.io/docs/recipes/custom-domain/) for more details.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center Domains 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: Domains
description: Custom domain lets you present a consistent brand by having your own domain name on the sign-in and registration pages. See [🌍 Custom domain](https://docs.logto.io/docs/recipes/custom-domain/) for more details.
paths:
/api/domains:
get:
operationId: ListDomains
tags:
- Domains
parameters: []
responses:
'200':
description: A list of domains.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- domain
- status
- errorMessage
- dnsRecords
- createdAt
properties:
id:
type: string
minLength: 1
maxLength: 21
domain:
type: string
minLength: 1
maxLength: 256
status:
type: string
enum:
- PendingVerification
- PendingSsl
- Active
- Error
errorMessage:
type: string
maxLength: 1024
nullable: true
dnsRecords:
type: array
items:
type: object
required:
- name
- type
- value
properties:
name:
type: string
type:
type: string
value:
type: string
createdAt:
type: number
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get domains
description: Get all of your custom domains.
post:
operationId: CreateDomain
tags:
- Domains
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
minLength: 1
maxLength: 256
description: The domain name, e.g. `example.com`.
responses:
'201':
description: The domain was created successfully.
content:
application/json:
schema:
type: object
required:
- id
- domain
- status
- errorMessage
- dnsRecords
- createdAt
properties:
id:
type: string
minLength: 1
maxLength: 21
domain:
type: string
minLength: 1
maxLength: 256
status:
type: string
enum:
- PendingVerification
- PendingSsl
- Active
- Error
errorMessage:
type: string
maxLength: 1024
nullable: true
dnsRecords:
type: array
items:
type: object
required:
- name
- type
- value
properties:
name:
type: string
type:
type: string
value:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error. Please check the request body.
summary: Create domain
description: Create a new domain with the given data. The maximum domain number is 1, once created, can not be modified, you'll have to delete and recreate one.
/api/domains/{id}:
get:
operationId: GetDomain
tags:
- Domains
parameters:
- $ref: '#/components/parameters/domainId-root'
responses:
'200':
description: Details of the domain.
content:
application/json:
schema:
type: object
required:
- id
- domain
- status
- errorMessage
- dnsRecords
- createdAt
properties:
id:
type: string
minLength: 1
maxLength: 21
domain:
type: string
minLength: 1
maxLength: 256
status:
type: string
enum:
- PendingVerification
- PendingSsl
- Active
- Error
errorMessage:
type: string
maxLength: 1024
nullable: true
dnsRecords:
type: array
items:
type: object
required:
- name
- type
- value
properties:
name:
type: string
type:
type: string
value:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The domain with the specified ID was not found.
summary: Get domain
description: Get domain details by ID, by calling this API, the domain status will be synced from remote provider.
delete:
operationId: DeleteDomain
tags:
- Domains
parameters:
- $ref: '#/components/parameters/domainId-root'
responses:
'204':
description: The domain was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The domain with the specified ID was not found.
summary: Delete domain
description: Delete domain by ID.
/api/domains/cleanup:
post:
operationId: CleanupDomains
tags:
- Domains
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- staleDays
properties:
staleDays:
type: number
description: The number of days a domain must be inactive before it is considered stale and eligible for cleanup.
responses:
'200':
description: The cleanup result summary.
content:
application/json:
schema:
type: object
required:
- scannedCount
- deletedCount
- skippedActiveCount
- failedCount
properties:
scannedCount:
type: number
deletedCount:
type: number
skippedActiveCount:
type: number
failedCount:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Cleanup stale domains
description: Clean up custom domains that have been inactive (not verified) for a specified number of days. This uses Cloudflare as the source of truth to determine domain activity.
components:
parameters:
domainId-root:
in: path
description: The unique identifier of the domain.
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