Endpoints for managing custom phrases that allow you to customize the phrases displayed in the sign-in experience. See [Localized language](https://docs.logto.io/docs/recipes/customize-sie/localized-language/) to learn more about custom phrases for localization.
openapi: 3.0.1
info:
title: Logto API references Account center Custom phrases 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: Custom phrases
description: 'Endpoints for managing custom phrases that allow you to customize the phrases displayed in the sign-in experience.
See [Localized language](https://docs.logto.io/docs/recipes/customize-sie/localized-language/) to learn more about custom phrases for localization.'
paths:
/api/custom-phrases:
get:
operationId: ListCustomPhrases
tags:
- Custom phrases
parameters: []
responses:
'200':
description: An array of custom phrases.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- languageTag
- translation
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
translation:
$ref: '#/components/schemas/TranslationObject'
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get all custom phrases
description: Get all custom phrases for all languages.
/api/custom-phrases/{languageTag}:
get:
operationId: GetCustomPhrase
tags:
- Custom phrases
parameters:
- name: languageTag
in: path
required: true
schema:
type: string
enum:
- af-ZA
- am-ET
- ar
- ar-AR
- as-IN
- az-AZ
- be-BY
- bg-BG
- bn-IN
- br-FR
- bs-BA
- ca-ES
- cb-IQ
- co-FR
- cs
- cs-CZ
- cx-PH
- cy-GB
- da-DK
- de
- de-DE
- el-GR
- en
- en-GB
- en-US
- eo-EO
- es
- es-ES
- es-419
- et-EE
- eu-ES
- fa-IR
- ff-NG
- fi
- fi-FI
- fo-FO
- fr
- fr-CA
- fr-FR
- fy-NL
- ga-IE
- gl-ES
- gn-PY
- gu-IN
- ha-NG
- he-IL
- hi-IN
- hr-HR
- ht-HT
- hu-HU
- hy-AM
- id-ID
- ik-US
- is-IS
- it
- it-IT
- iu-CA
- ja
- ja-JP
- ja-KS
- jv-ID
- ka-GE
- kk-KZ
- km-KH
- kn-IN
- ko
- ko-KR
- ku-TR
- ky-KG
- lo-LA
- lt-LT
- lv-LV
- mg-MG
- mk-MK
- ml-IN
- mn-MN
- mr-IN
- ms-MY
- mt-MT
- my-MM
- nb-NO
- ne-NP
- nl
- nl-BE
- nl-NL
- nn-NO
- or-IN
- pa-IN
- pl-PL
- ps-AF
- pt
- pt-BR
- pt-PT
- ro-RO
- ru
- ru-RU
- rw-RW
- sc-IT
- si-LK
- sk-SK
- sl-SI
- sn-ZW
- sq-AL
- sr-RS
- sv
- sv-SE
- sw-KE
- sy-SY
- sz-PL
- ta-IN
- te-IN
- tg-TJ
- th
- th-TH
- tl-PH
- tr
- tr-TR
- tt-RU
- tz-MA
- uk-UA
- ur-PK
- uz-UZ
- vi-VN
- zh
- zh-CN
- zh-HK
- zh-MO
- zh-TW
- zz-TR
responses:
'200':
description: Custom phrases for the specified language tag.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- languageTag
- translation
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
translation:
$ref: '#/components/schemas/TranslationObject'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Custom phrases not found.
summary: Get custom phrases
description: Get custom phrases for the specified language tag.
put:
operationId: ReplaceCustomPhrase
tags:
- Custom phrases
parameters:
- name: languageTag
in: path
required: true
schema:
type: string
enum:
- af-ZA
- am-ET
- ar
- ar-AR
- as-IN
- az-AZ
- be-BY
- bg-BG
- bn-IN
- br-FR
- bs-BA
- ca-ES
- cb-IQ
- co-FR
- cs
- cs-CZ
- cx-PH
- cy-GB
- da-DK
- de
- de-DE
- el-GR
- en
- en-GB
- en-US
- eo-EO
- es
- es-ES
- es-419
- et-EE
- eu-ES
- fa-IR
- ff-NG
- fi
- fi-FI
- fo-FO
- fr
- fr-CA
- fr-FR
- fy-NL
- ga-IE
- gl-ES
- gn-PY
- gu-IN
- ha-NG
- he-IL
- hi-IN
- hr-HR
- ht-HT
- hu-HU
- hy-AM
- id-ID
- ik-US
- is-IS
- it
- it-IT
- iu-CA
- ja
- ja-JP
- ja-KS
- jv-ID
- ka-GE
- kk-KZ
- km-KH
- kn-IN
- ko
- ko-KR
- ku-TR
- ky-KG
- lo-LA
- lt-LT
- lv-LV
- mg-MG
- mk-MK
- ml-IN
- mn-MN
- mr-IN
- ms-MY
- mt-MT
- my-MM
- nb-NO
- ne-NP
- nl
- nl-BE
- nl-NL
- nn-NO
- or-IN
- pa-IN
- pl-PL
- ps-AF
- pt
- pt-BR
- pt-PT
- ro-RO
- ru
- ru-RU
- rw-RW
- sc-IT
- si-LK
- sk-SK
- sl-SI
- sn-ZW
- sq-AL
- sr-RS
- sv
- sv-SE
- sw-KE
- sy-SY
- sz-PL
- ta-IN
- te-IN
- tg-TJ
- th
- th-TH
- tl-PH
- tr
- tr-TR
- tt-RU
- tz-MA
- uk-UA
- ur-PK
- uz-UZ
- vi-VN
- zh
- zh-CN
- zh-HK
- zh-MO
- zh-TW
- zz-TR
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationObject'
example:
phraseKey1: new value1
phraseKey2: new value2
responses:
'201':
description: Custom phrases created or updated successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- languageTag
- translation
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
translation:
$ref: '#/components/schemas/TranslationObject'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Invalid translation structure.
summary: Upsert custom phrases
description: Upsert custom phrases for the specified language tag. Upsert means that if the custom phrases already exist, they will be updated. Otherwise, they will be created.
delete:
operationId: DeleteCustomPhrase
tags:
- Custom phrases
parameters:
- name: languageTag
in: path
required: true
schema:
type: string
enum:
- af-ZA
- am-ET
- ar
- ar-AR
- as-IN
- az-AZ
- be-BY
- bg-BG
- bn-IN
- br-FR
- bs-BA
- ca-ES
- cb-IQ
- co-FR
- cs
- cs-CZ
- cx-PH
- cy-GB
- da-DK
- de
- de-DE
- el-GR
- en
- en-GB
- en-US
- eo-EO
- es
- es-ES
- es-419
- et-EE
- eu-ES
- fa-IR
- ff-NG
- fi
- fi-FI
- fo-FO
- fr
- fr-CA
- fr-FR
- fy-NL
- ga-IE
- gl-ES
- gn-PY
- gu-IN
- ha-NG
- he-IL
- hi-IN
- hr-HR
- ht-HT
- hu-HU
- hy-AM
- id-ID
- ik-US
- is-IS
- it
- it-IT
- iu-CA
- ja
- ja-JP
- ja-KS
- jv-ID
- ka-GE
- kk-KZ
- km-KH
- kn-IN
- ko
- ko-KR
- ku-TR
- ky-KG
- lo-LA
- lt-LT
- lv-LV
- mg-MG
- mk-MK
- ml-IN
- mn-MN
- mr-IN
- ms-MY
- mt-MT
- my-MM
- nb-NO
- ne-NP
- nl
- nl-BE
- nl-NL
- nn-NO
- or-IN
- pa-IN
- pl-PL
- ps-AF
- pt
- pt-BR
- pt-PT
- ro-RO
- ru
- ru-RU
- rw-RW
- sc-IT
- si-LK
- sk-SK
- sl-SI
- sn-ZW
- sq-AL
- sr-RS
- sv
- sv-SE
- sw-KE
- sy-SY
- sz-PL
- ta-IN
- te-IN
- tg-TJ
- th
- th-TH
- tl-PH
- tr
- tr-TR
- tt-RU
- tz-MA
- uk-UA
- ur-PK
- uz-UZ
- vi-VN
- zh
- zh-CN
- zh-HK
- zh-MO
- zh-TW
- zz-TR
responses:
'204':
description: Custom phrases deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Custom phrases not found.
'409':
description: Cannot delete the default language.
summary: Delete custom phrase
description: Delete custom phrases for the specified language tag.
components:
schemas:
Translation:
oneOf:
- type: string
TranslationObject:
type: object
properties:
'[translationKey]':
$ref: '#/components/schemas/Translation'
example:
input:
username: Username
password: Password
action:
sign_in: Sign In
continue: Continue
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