Endpoints for managing Logto global configurations for the tenant, such as admin console config and OIDC signing keys. See [🔑 Signing keys](https://docs.logto.io/docs/recipes/signing-keys-rotation/) to learn more about signing keys and key rotation.
openapi: 3.0.1
info:
title: Logto API references Account center Configs 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: Configs
description: 'Endpoints for managing Logto global configurations for the tenant, such as admin console config and OIDC signing keys.
See [🔑 Signing keys](https://docs.logto.io/docs/recipes/signing-keys-rotation/) to learn more about signing keys and key rotation.'
paths:
/api/configs/admin-console:
get:
operationId: GetAdminConsoleConfig
tags:
- Configs
parameters: []
responses:
'200':
description: The configuration object.
content:
application/json:
schema:
type: object
required:
- signInExperienceCustomized
- organizationCreated
properties:
signInExperienceCustomized:
type: boolean
organizationCreated:
type: boolean
developmentTenantMigrationNotification:
type: object
required:
- isPaidTenant
- tag
properties:
isPaidTenant:
type: boolean
tag:
type: string
readAt:
type: number
checkedChargeNotification:
type: object
properties:
token:
type: boolean
apiResource:
type: boolean
machineToMachineApp:
type: boolean
tenantMember:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Configuration not found.
summary: Get admin console config
description: Get the global configuration object for Logto Console.
patch:
operationId: UpdateAdminConsoleConfig
tags:
- Configs
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
signInExperienceCustomized:
type: boolean
organizationCreated:
type: boolean
developmentTenantMigrationNotification:
type: object
required:
- isPaidTenant
- tag
properties:
isPaidTenant:
type: boolean
tag:
type: string
readAt:
type: number
checkedChargeNotification:
type: object
properties:
token:
type: boolean
apiResource:
type: boolean
machineToMachineApp:
type: boolean
tenantMember:
type: boolean
responses:
'200':
description: The updated configuration object.
content:
application/json:
schema:
type: object
required:
- signInExperienceCustomized
- organizationCreated
properties:
signInExperienceCustomized:
type: boolean
organizationCreated:
type: boolean
developmentTenantMigrationNotification:
type: object
required:
- isPaidTenant
- tag
properties:
isPaidTenant:
type: boolean
tag:
type: string
readAt:
type: number
checkedChargeNotification:
type: object
properties:
token:
type: boolean
apiResource:
type: boolean
machineToMachineApp:
type: boolean
tenantMember:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Configuration not found.
summary: Update admin console config
description: Update the global configuration object for Logto Console. This method performs a partial update.
/api/configs/oidc/session:
get:
operationId: GetOidcSessionConfig
tags:
- Configs
parameters: []
responses:
'200':
description: The OIDC session configuration. Returns empty object if the configuration does not exist.
content:
application/json:
schema:
type: object
required:
- ttl
properties:
ttl:
type: number
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get OIDC session config
description: 'Get the OIDC session configuration for the tenant. '
patch:
operationId: UpdateOidcSessionConfig
tags:
- Configs
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ttl:
type: number
responses:
'200':
description: The updated OIDC session configuration.
content:
application/json:
schema:
type: object
required:
- ttl
properties:
ttl:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Update OIDC session config
description: Update the OIDC session configuration for the tenant. This method performs a partial update. If the configuration does not exist, it will be created.
/api/configs/oidc/{keyType}:
get:
operationId: GetOidcKeys
tags:
- Configs
parameters:
- name: keyType
in: path
required: true
schema:
type: string
enum:
- private-keys
- cookie-keys
description: Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead.
responses:
'200':
description: An array of OIDC signing keys for the given key type.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- createdAt
properties:
id:
type: string
createdAt:
type: number
signingKeyAlgorithm:
type: string
enum:
- RSA
- EC
status:
type: string
enum:
- Next
- Current
- Previous
effectiveAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get OIDC keys
description: Get OIDC signing keys by key type. The actual key will be redacted from the result.
/api/configs/oidc/{keyType}/{keyId}:
delete:
operationId: DeleteOidcKey
tags:
- Configs
parameters:
- name: keyType
in: path
required: true
schema:
type: string
enum:
- private-keys
- cookie-keys
description: Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead.
- $ref: '#/components/parameters/keyId'
responses:
'204':
description: The key was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The key was not found.
'422':
description: At least one key must be kept.
summary: Delete OIDC key
description: Delete an OIDC signing key by key type and key ID.
/api/configs/oidc/{keyType}/rotate:
post:
operationId: RotateOidcKeys
tags:
- Configs
parameters:
- name: keyType
in: path
required: true
schema:
type: string
enum:
- private-keys
- cookie-keys
description: Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
signingKeyAlgorithm:
type: string
enum:
- RSA
- EC
description: 'The signing key algorithm the new generated private key is using.
Only applicable when `keyType` is `private-keys`.'
rotationGracePeriod:
type: number
responses:
'200':
description: An array of OIDC signing keys after rotation.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- createdAt
properties:
id:
type: string
createdAt:
type: number
signingKeyAlgorithm:
type: string
enum:
- RSA
- EC
status:
type: string
enum:
- Next
- Current
- Previous
effectiveAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Unprocessable Content
summary: Rotate OIDC keys
description: 'A new key will be generated and prepend to the list of keys.
Only two recent keys will be kept. The oldest key will be automatically removed if there are more than two keys.'
/api/configs/jwt-customizer/{tokenTypePath}:
put:
operationId: UpsertJwtCustomizer
tags:
- Configs
parameters:
- name: tokenTypePath
in: path
required: true
schema:
type: string
enum:
- access-token
- client-credentials
description: The token type to create a JWT customizer for.
requestBody:
required: true
content:
application/json:
schema:
example: {}
properties:
script:
description: The script of the JWT customizer.
environmentVariables:
description: The environment variables for the JWT customizer.
contextSample:
description: The sample context for the JWT customizer script testing purpose.
tokenSample:
description: The sample raw token payload for the JWT customizer script testing purpose.
blockIssuanceOnError:
description: Whether to block token issuance when the JWT customizer script fails.
responses:
'200':
description: The updated JWT customizer.
content:
application/json:
schema:
oneOf:
- type: object
required:
- script
properties:
script:
type: string
environmentVariables:
type: object
additionalProperties:
type: string
contextSample:
type: object
required:
- user
properties:
user:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- issuer
- identityId
- detail
properties:
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
mfaVerificationFactors:
type: array
items:
type: string
enum:
- Totp
- WebAuthn
- BackupCode
- EmailVerificationCode
- PhoneVerificationCode
roles:
type: array
items:
type: object
required:
- id
- name
- description
- scopes
properties:
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
minLength: 1
maxLength: 128
scopes:
type: array
items:
type: object
required:
- id
- name
- description
- resourceId
- resource
properties:
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description:
type: string
nullable: true
resourceId:
type: string
minLength: 1
maxLength: 21
resource:
type: object
required:
- tenantId
- id
- name
- indicator
- isDefault
- accessTokenTtl
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
indicator:
type: string
minLength: 1
isDefault:
type: boolean
accessTokenTtl:
type: number
organizations:
type: array
items:
type: object
required:
- id
- name
- description
properties:
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 128
description:
type: string
maxLength: 256
nullable: true
organizationRoles:
type: array
items:
type: object
required:
- organizationId
- roleId
- roleName
properties:
organizationId:
type: string
roleId:
type: string
roleName:
type: string
grant:
type: object
properties:
type:
type: string
format: '"urn:ietf:params:oauth:grant-type:token-exchange"'
subjectTokenContext:
type: object
description: arbitrary
interaction:
type: object
properties:
interactionEvent:
type: string
enum:
- SignIn
- Register
- ForgotPassword
userId:
type: string
verificationRecords:
type: array
items:
oneOf:
- type: object
required:
- id
- type
- identifier
- verified
properties:
id:
type: string
type:
type: string
format: '"Password"'
identifier:
type: object
required:
- type
- value
properties:
type:
oneOf:
- type: string
enum:
- username
- email
- phone
- type: string
enum:
- userId
value:
type: string
verified:
type: boolean
- type: object
required:
- id
- templateType
- verified
- type
- identifier
properties:
id:
type: string
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
verified:
type: boolean
type:
type: string
format: '"EmailVerificationCode"'
identifier:
type: object
required:
- type
- value
properties:
type:
type: string
format: '"email"'
value:
type: string
- type: object
required:
- id
- templateType
- verified
- type
- identifier
properties:
id:
type: string
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
verified:
type: boolean
type:
type: string
format: '"PhoneVerificationCode"'
identifier:
type: object
required:
- type
- value
properties:
type:
type: string
format: '"phone"'
value:
type: string
- type: object
required:
- id
- templateType
- verified
- type
- identifier
properties:
id:
type: string
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
verified:
type: boolean
type:
type: string
# --- truncated at 32 KB (337 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-configs-api-openapi.yml