Logto API references
Cloud

Base URL 
https://[tenant_id].logto.app

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.

This is version Cloud of this API documentation. Last update on Mar 31, 2025.

Applications

Application represents your registered software program or service that has been authorized to access user information and perform actions on behalf of users within the system. Currently, Logto supports four types of applications:

  • Traditional web

  • Single-page app

  • Native app

  • Machine-to-machine app.

Depending on the application type, it may have different authentication flows and access to the system. See 🔗 Integrate Logto in your application to learn more about how to integrate Logto into your application.

Role-based access control (RBAC) is supported for machine-to-machine applications. See 🔐 Role-based access control (RBAC) to get started with role-based access control.

Get applications

GET /api/applications
O auth2

Get applications that match the given query with pagination.

Query parameters

  • types array[string] | string

    An array of application types to filter applications.

  • excludeRoleId string
  • excludeOrganizationId string
  • isThirdParty string("true") | string("false")
  • page integer

    Page number (starts from 1).

    Minimum value is 1. Default value is 1.

  • page_size integer

    Entries per page.

    Minimum value is 1. Default value is 20.

  • search_params object

    Search query parameters.

    Hide search_params attribute Show search_params attribute object
    • * string Additional properties

Responses

GET /api/applications 
curl \
 --request GET 'https://[tenant_id].logto.app/api/applications' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "tenantId": "string",
    "id": "string",
    "name": "string",
    "secret": "string",
    "description": "string",
    "type": "Native",
    "oidcClientMetadata": {
      "redirectUris": [
        {}
      ],
      "postLogoutRedirectUris": [
        "string"
      ],
      "backchannelLogoutUri": "string",
      "backchannelLogoutSessionRequired": true,
      "logoUri": "string"
    },
    "customClientMetadata": {
      "corsAllowedOrigins": [
        "string"
      ],
      "idTokenTtl": 42.0,
      "refreshTokenTtl": 42.0,
      "refreshTokenTtlInDays": 42.0,
      "tenantId": "string",
      "alwaysIssueRefreshToken": true,
      "rotateRefreshToken": true
    },
    "protectedAppMetadata": {
      "host": "string",
      "origin": "string",
      "sessionDuration": 42.0,
      "pageRules": [
        {
          "path": "string"
        }
      ],
      "customDomains": [
        {
          "domain": "string",
          "status": "PendingVerification",
          "errorMessage": "string",
          "dnsRecords": [
            {
              "name": "string",
              "type": "string",
              "value": "string"
            }
          ],
          "cloudflareData": {
            "id": "string",
            "status": "string",
            "ssl": {
              "status": "string",
              "validation_errors": [
                {
                  "message": "string"
                }
              ]
            },
            "verification_errors": [
              "string"
            ]
          }
        }
      ]
    },
    "customData": {},
    "isThirdParty": true,
    "createdAt": 42.0
  }
]

Get application

GET /api/applications/{id}
O auth2

Get application details by ID.

Path parameters

  • id string Required

    The unique identifier of the application.

Responses

GET /api/applications/{id} 
curl \
 --request GET 'https://[tenant_id].logto.app/api/applications/{id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "tenantId": "string",
  "id": "string",
  "name": "string",
  "secret": "string",
  "description": "string",
  "type": "Native",
  "oidcClientMetadata": {
    "redirectUris": [
      {}
    ],
    "postLogoutRedirectUris": [
      "string"
    ],
    "backchannelLogoutUri": "string",
    "backchannelLogoutSessionRequired": true,
    "logoUri": "string"
  },
  "customClientMetadata": {
    "corsAllowedOrigins": [
      "string"
    ],
    "idTokenTtl": 42.0,
    "refreshTokenTtl": 42.0,
    "refreshTokenTtlInDays": 42.0,
    "tenantId": "string",
    "alwaysIssueRefreshToken": true,
    "rotateRefreshToken": true
  },
  "protectedAppMetadata": {
    "host": "string",
    "origin": "string",
    "sessionDuration": 42.0,
    "pageRules": [
      {
        "path": "string"
      }
    ],
    "customDomains": [
      {
        "domain": "string",
        "status": "PendingVerification",
        "errorMessage": "string",
        "dnsRecords": [
          {
            "name": "string",
            "type": "string",
            "value": "string"
          }
        ],
        "cloudflareData": {
          "id": "string",
          "status": "string",
          "ssl": {
            "status": "string",
            "validation_errors": [
              {
                "message": "string"
              }
            ]
          },
          "verification_errors": [
            "string"
          ]
        }
      }
    ]
  },
  "customData": {},
  "isThirdParty": true,
  "createdAt": 42.0,
  "isAdmin": true
}

Update application custom data

PATCH /api/applications/{applicationId}/custom-data
O auth2

Update the custom data of an application.

Path parameters

application/json

Body Required

object object

An arbitrary JSON object.

Responses

  • 200 application/json

    The updated custom data in JSON.

    arbitrary
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

PATCH /api/applications/{applicationId}/custom-data 
curl \
 --request PATCH 'https://[tenant_id].logto.app/api/applications/{applicationId}/custom-data' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json"
Request examples 
{}
Response examples (200) 
{}

Remove a API resource role from application

DELETE /api/applications/{applicationId}/roles/{roleId}
O auth2

Remove a API resource role from the specified application.

Path parameters

  • applicationId string Required

    The unique identifier of the application.

  • roleId string Required

    The unique identifier of the role.

Responses

  • 204

    The API resource role has been removed from the application successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

  • 422

    Unprocessable Content

DELETE /api/applications/{applicationId}/roles/{roleId} 
curl \
 --request DELETE 'https://[tenant_id].logto.app/api/applications/{applicationId}/roles/{roleId}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Add a custom domain to the application.

POST /api/applications/{id}/protected-app-metadata/custom-domains
O auth2

Add a custom domain to the application. You'll need to setup DNS record later.

Path parameters

  • id string Required

    The unique identifier of the application.

application/json

Body Required

  • domain string Required

    The domain to be added to the application.

Responses

  • 201 application/json

    The domain has been added to the application.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

  • 409

    The domain already exists.

  • 422

    Exeeded the maximum number of domains allowed or the domain is invalid.

  • 501

    Not Implemented

POST /api/applications/{id}/protected-app-metadata/custom-domains 
curl \
 --request POST 'https://[tenant_id].logto.app/api/applications/{id}/protected-app-metadata/custom-domains' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"domain":"string"}'
Request examples 
{
  "domain": "string"
}

Get application secrets

GET /api/applications/{id}/secrets
O auth2

Get all the secrets for the application.

Path parameters

  • id string Required

    The unique identifier of the application.

Responses

  • 200 application/json

    A list of secrets.

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • applicationId string Required

      Minimum length is 1, maximum length is 21.

    • name string Required

      Minimum length is 1, maximum length is 256.

    • value string Required

      Minimum length is 1, maximum length is 64.

    • createdAt number Required
    • expiresAt number | null Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

GET /api/applications/{id}/secrets 
curl \
 --request GET 'https://[tenant_id].logto.app/api/applications/{id}/secrets' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "tenantId": "string",
    "applicationId": "string",
    "name": "string",
    "value": "string",
    "createdAt": 42.0,
    "expiresAt": 42.0
  }
]

Add application secret

POST /api/applications/{id}/secrets
O auth2

Add a new secret for the application.

Path parameters

  • id string Required

    The unique identifier of the application.

application/json

Body Required

  • name string Required

    The secret name. Must be unique within the application.

    Minimum length is 1, maximum length is 256.

  • expiresAt number | null

    The epoch time in milliseconds when the secret will expire. If not provided, the secret will never expire.

Responses

  • 201 application/json

    The secret was added successfully.

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • applicationId string Required

      Minimum length is 1, maximum length is 21.

    • name string Required

      Minimum length is 1, maximum length is 256.

    • value string Required

      Minimum length is 1, maximum length is 64.

    • createdAt number Required
    • expiresAt number | null Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    The secret name is already in use.

POST /api/applications/{id}/secrets 
curl \
 --request POST 'https://[tenant_id].logto.app/api/applications/{id}/secrets' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"string","expiresAt":42.0}'
Request examples 
{
  "name": "string",
  "expiresAt": 42.0
}
Response examples (201) 
{
  "tenantId": "string",
  "applicationId": "string",
  "name": "string",
  "value": "string",
  "createdAt": 42.0,
  "expiresAt": 42.0
}

Update application secret

PATCH /api/applications/{id}/secrets/{name}
O auth2

Update a secret for the application by name.

Path parameters

  • id string Required

    The unique identifier of the application.

  • name string Required

    The name of the secret.

application/json

Body Required

  • name string Required

    The secret name to update. Must be unique within the application.

    Minimum length is 1, maximum length is 256.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • applicationId string Required

      Minimum length is 1, maximum length is 21.

    • name string Required

      Minimum length is 1, maximum length is 256.

    • value string Required

      Minimum length is 1, maximum length is 64.

    • createdAt number Required
    • expiresAt number | null Required
  • 204

    The secret was updated successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

PATCH /api/applications/{id}/secrets/{name} 
curl \
 --request PATCH 'https://[tenant_id].logto.app/api/applications/{id}/secrets/{name}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"string"}'
Request examples 
{
  "name": "string"
}
Response examples (200) 
{
  "tenantId": "string",
  "applicationId": "string",
  "name": "string",
  "value": "string",
  "createdAt": 42.0,
  "expiresAt": 42.0
}

Remove user consent scope from application.

DELETE /api/applications/{applicationId}/user-consent-scopes/{scopeType}/{scopeId}
O auth2

Remove the user consent scope from an application by application id, scope type and scope id

Path parameters

  • applicationId string Required

    The unique identifier of the application.

  • scopeType string Required

    Values are organization-scopes, resource-scopes, organization-resource-scopes, or user-scopes.

  • scopeId string Required

    The unique identifier of the scope.

Responses

  • 204

    The user consent scope is removed from the application successfully

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    The application or scope is not found

DELETE /api/applications/{applicationId}/user-consent-scopes/{scopeType}/{scopeId} 
curl \
 --request DELETE 'https://[tenant_id].logto.app/api/applications/{applicationId}/user-consent-scopes/{scopeType}/{scopeId}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Update application level sign-in experience

PUT /api/applications/{applicationId}/sign-in-experience
O auth2

Update application level sign-in experience for the specified application. Create a new sign-in experience if it does not exist.

  • Only branding properties and terms links customization is supported for now.

  • Only third-party applications can be customized for now.

  • Application level sign-in experience customization is optional, if provided, it will override the default branding and terms links.

Path parameters

application/json

Body Required

Responses

PUT /api/applications/{applicationId}/sign-in-experience 
curl \
 --request PUT 'https://[tenant_id].logto.app/api/applications/{applicationId}/sign-in-experience' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"color":{"primaryColor":"string","isDarkModeEnabled":true,"darkPrimaryColor":"string"},"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"displayName":"string","termsOfUseUrl":"string","privacyPolicyUrl":"string"}'
Request examples 
{
  "color": {
    "primaryColor": "string",
    "isDarkModeEnabled": true,
    "darkPrimaryColor": "string"
  },
  "branding": {
    "logoUrl": "string",
    "darkLogoUrl": "string",
    "favicon": "string",
    "darkFavicon": "string"
  },
  "displayName": "string",
  "termsOfUseUrl": "string",
  "privacyPolicyUrl": "string"
}
Response examples (200) 
{
  "tenantId": "string",
  "applicationId": "string",
  "color": {
    "primaryColor": "string",
    "isDarkModeEnabled": true,
    "darkPrimaryColor": "string"
  },
  "branding": {
    "logoUrl": "string",
    "darkLogoUrl": "string",
    "favicon": "string",
    "darkFavicon": "string"
  },
  "termsOfUseUrl": "string",
  "privacyPolicyUrl": "string",
  "displayName": "string"
}
Response examples (201) 
{
  "tenantId": "string",
  "applicationId": "string",
  "color": {
    "primaryColor": "string",
    "isDarkModeEnabled": true,
    "darkPrimaryColor": "string"
  },
  "branding": {
    "logoUrl": "string",
    "darkLogoUrl": "string",
    "favicon": "string",
    "darkFavicon": "string"
  },
  "termsOfUseUrl": "string",
  "privacyPolicyUrl": "string",
  "displayName": "string"
}

Get logs

GET /api/logs
O auth2

Get logs that match the given query with pagination.

Query parameters

  • userId string

    Filter logs by user ID.

  • applicationId string

    Filter logs by application ID.

  • logKey string

    Filter logs by log key.

  • page integer

    Page number (starts from 1).

    Minimum value is 1. Default value is 1.

  • page_size integer

    Entries per page.

    Minimum value is 1. Default value is 20.

Responses

GET /api/logs 
curl \
 --request GET 'https://[tenant_id].logto.app/api/logs' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "tenantId": "string",
    "id": "string",
    "key": "string",
    "payload": {
      "key": "string",
      "result": "Success",
      "error": {},
      "ip": "string",
      "userAgent": "string",
      "userId": "string",
      "applicationId": "string",
      "sessionId": "string",
      "params": {}
    },
    "createdAt": 42.0
  }
]

Hasura auth hook endpoint

GET /api/authn/hasura

The HASURA_GRAPHQL_AUTH_HOOK endpoint for Hasura auth. Use this endpoint to integrate Hasura's webhook authentication flow.

Query parameters

Responses

GET /api/authn/hasura 
curl \
 --request GET 'https://[tenant_id].logto.app/api/authn/hasura?resource=string'
Response examples (200) 
{
  "X-Hasura-User-Id": "string",
  "X-Hasura-Role": "string"
}

Get captcha provider

GET /api/captcha-provider
O auth2

Get the captcha provider, you can only have one captcha provider.

Responses

GET /api/captcha-provider 
curl \
 --request GET 'https://[tenant_id].logto.app/api/captcha-provider' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "tenantId": "string",
  "id": "string",
  "config": {
    "type": "string",
    "siteKey": "string",
    "secretKey": "string"
  },
  "createdAt": 42.0,
  "updatedAt": 42.0
}

Update captcha provider

PUT /api/captcha-provider
O auth2

Update the captcha provider with the provided settings.

application/json

Body Required

Responses

PUT /api/captcha-provider 
curl \
 --request PUT 'https://[tenant_id].logto.app/api/captcha-provider' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"config":{"type":"string","siteKey":"string","secretKey":"string"}}'
Request examples 
{
  "config": {
    "type": "string",
    "siteKey": "string",
    "secretKey": "string"
  }
}
Response examples (200) 
{
  "tenantId": "string",
  "id": "string",
  "config": {
    "type": "string",
    "siteKey": "string",
    "secretKey": "string"
  },
  "createdAt": 42.0,
  "updatedAt": 42.0
}

Get OIDC keys

GET /api/configs/oidc/{keyType}
O auth2

Get OIDC signing keys by key type. The actual key will be redacted from the result.

Path parameters

  • keyType string Required

    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.

    Values are private-keys or cookie-keys.

Responses

GET /api/configs/oidc/{keyType} 
curl \
 --request GET 'https://[tenant_id].logto.app/api/configs/oidc/{keyType}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "id": "string",
    "createdAt": 42.0,
    "signingKeyAlgorithm": "RSA"
  }
]

Get JWT customizer

GET /api/configs/jwt-customizer/{tokenTypePath}
O auth2

Get the JWT customizer for the given token type.

Path parameters

  • tokenTypePath string Required

    The token type to get the JWT customizer for.

    Values are access-token or client-credentials.

Responses

GET /api/configs/jwt-customizer/{tokenTypePath} 
curl \
 --request GET 'https://[tenant_id].logto.app/api/configs/jwt-customizer/{tokenTypePath}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {
    "user": {
      "id": "string",
      "username": "string",
      "primaryEmail": "string",
      "primaryPhone": "string",
      "name": "string",
      "avatar": "string",
      "customData": {},
      "identities": {
        "additionalProperty1": {
          "userId": "string",
          "details": {}
        },
        "additionalProperty2": {
          "userId": "string",
          "details": {}
        }
      },
      "lastSignInAt": 42.0,
      "createdAt": 42.0,
      "updatedAt": 42.0,
      "profile": {
        "familyName": "string",
        "givenName": "string",
        "middleName": "string",
        "nickname": "string",
        "preferredUsername": "string",
        "profile": "string",
        "website": "string",
        "gender": "string",
        "birthdate": "string",
        "zoneinfo": "string",
        "locale": "string",
        "address": {
          "formatted": "string",
          "streetAddress": "string",
          "locality": "string",
          "region": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "applicationId": "string",
      "isSuspended": true,
      "hasPassword": true,
      "ssoIdentities": [
        {
          "issuer": "string",
          "identityId": "string",
          "detail": {}
        }
      ],
      "mfaVerificationFactors": [
        "Totp"
      ],
      "roles": [
        {
          "id": "string",
          "name": "string",
          "description": "string",
          "scopes": [
            {
              "id": "string",
              "name": "string",
              "description": "string",
              "resourceId": "string",
              "resource": {
                "tenantId": "string",
                "id": "string",
                "name": "string",
                "indicator": "string",
                "isDefault": true,
                "accessTokenTtl": 42.0
              }
            }
          ]
        }
      ],
      "organizations": [
        {
          "id": "string",
          "name": "string",
          "description": "string"
        }
      ],
      "organizationRoles": [
        {
          "organizationId": "string",
          "roleId": "string",
          "roleName": "string"
        }
      ]
    },
    "grant": {
      "type": "string",
      "subjectTokenContext": {}
    }
  },
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "accountId": "string",
    "expiresWithSession": true,
    "grantId": "string",
    "gty": "string",
    "sessionUid": "string",
    "sid": "string",
    "kind": "string"
  }
}
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {},
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "kind": "string"
  }
}

Create or update JWT customizer

PUT /api/configs/jwt-customizer/{tokenTypePath}
O auth2

Create or update a JWT customizer for the given token type.

Path parameters

  • tokenTypePath string Required

    The token type to create a JWT customizer for.

    Values are access-token or client-credentials.

application/json

Body Required

Responses

PUT /api/configs/jwt-customizer/{tokenTypePath} 
curl \
 --request PUT 'https://[tenant_id].logto.app/api/configs/jwt-customizer/{tokenTypePath}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json"
Request examples 
{}
Response examples (200) 
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {
    "user": {
      "id": "string",
      "username": "string",
      "primaryEmail": "string",
      "primaryPhone": "string",
      "name": "string",
      "avatar": "string",
      "customData": {},
      "identities": {
        "additionalProperty1": {
          "userId": "string",
          "details": {}
        },
        "additionalProperty2": {
          "userId": "string",
          "details": {}
        }
      },
      "lastSignInAt": 42.0,
      "createdAt": 42.0,
      "updatedAt": 42.0,
      "profile": {
        "familyName": "string",
        "givenName": "string",
        "middleName": "string",
        "nickname": "string",
        "preferredUsername": "string",
        "profile": "string",
        "website": "string",
        "gender": "string",
        "birthdate": "string",
        "zoneinfo": "string",
        "locale": "string",
        "address": {
          "formatted": "string",
          "streetAddress": "string",
          "locality": "string",
          "region": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "applicationId": "string",
      "isSuspended": true,
      "hasPassword": true,
      "ssoIdentities": [
        {
          "issuer": "string",
          "identityId": "string",
          "detail": {}
        }
      ],
      "mfaVerificationFactors": [
        "Totp"
      ],
      "roles": [
        {
          "id": "string",
          "name": "string",
          "description": "string",
          "scopes": [
            {
              "id": "string",
              "name": "string",
              "description": "string",
              "resourceId": "string",
              "resource": {
                "tenantId": "string",
                "id": "string",
                "name": "string",
                "indicator": "string",
                "isDefault": true,
                "accessTokenTtl": 42.0
              }
            }
          ]
        }
      ],
      "organizations": [
        {
          "id": "string",
          "name": "string",
          "description": "string"
        }
      ],
      "organizationRoles": [
        {
          "organizationId": "string",
          "roleId": "string",
          "roleName": "string"
        }
      ]
    },
    "grant": {
      "type": "string",
      "subjectTokenContext": {}
    }
  },
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "accountId": "string",
    "expiresWithSession": true,
    "grantId": "string",
    "gty": "string",
    "sessionUid": "string",
    "sid": "string",
    "kind": "string"
  }
}
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {},
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "kind": "string"
  }
}
Response examples (201) 
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {
    "user": {
      "id": "string",
      "username": "string",
      "primaryEmail": "string",
      "primaryPhone": "string",
      "name": "string",
      "avatar": "string",
      "customData": {},
      "identities": {
        "additionalProperty1": {
          "userId": "string",
          "details": {}
        },
        "additionalProperty2": {
          "userId": "string",
          "details": {}
        }
      },
      "lastSignInAt": 42.0,
      "createdAt": 42.0,
      "updatedAt": 42.0,
      "profile": {
        "familyName": "string",
        "givenName": "string",
        "middleName": "string",
        "nickname": "string",
        "preferredUsername": "string",
        "profile": "string",
        "website": "string",
        "gender": "string",
        "birthdate": "string",
        "zoneinfo": "string",
        "locale": "string",
        "address": {
          "formatted": "string",
          "streetAddress": "string",
          "locality": "string",
          "region": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "applicationId": "string",
      "isSuspended": true,
      "hasPassword": true,
      "ssoIdentities": [
        {
          "issuer": "string",
          "identityId": "string",
          "detail": {}
        }
      ],
      "mfaVerificationFactors": [
        "Totp"
      ],
      "roles": [
        {
          "id": "string",
          "name": "string",
          "description": "string",
          "scopes": [
            {
              "id": "string",
              "name": "string",
              "description": "string",
              "resourceId": "string",
              "resource": {
                "tenantId": "string",
                "id": "string",
                "name": "string",
                "indicator": "string",
                "isDefault": true,
                "accessTokenTtl": 42.0
              }
            }
          ]
        }
      ],
      "organizations": [
        {
          "id": "string",
          "name": "string",
          "description": "string"
        }
      ],
      "organizationRoles": [
        {
          "organizationId": "string",
          "roleId": "string",
          "roleName": "string"
        }
      ]
    },
    "grant": {
      "type": "string",
      "subjectTokenContext": {}
    }
  },
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "accountId": "string",
    "expiresWithSession": true,
    "grantId": "string",
    "gty": "string",
    "sessionUid": "string",
    "sid": "string",
    "kind": "string"
  }
}
{
  "script": "string",
  "environmentVariables": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "contextSample": {},
  "tokenSample": {
    "jti": "string",
    "aud": "string",
    "scope": "string",
    "clientId": "string",
    "kind": "string"
  }
}

Get connector factory

GET /api/connector-factories/{id}
O auth2

Get connector factory by the given ID.

Path parameters

  • id string Required

    The unique identifier of the connector factory.

Responses

GET /api/connector-factories/{id} 
curl \
 --request GET 'https://[tenant_id].logto.app/api/connector-factories/{id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "type": "Email",
  "isDemo": true,
  "id": "string",
  "target": "string",
  "name": {},
  "description": {},
  "logo": "string",
  "logoDark": "string",
  "readme": "string",
  "configTemplate": "string",
  "formItems": [
    {
      "type": "string",
      "selectItems": [
        {
          "value": "string",
          "title": "string"
        }
      ],
      "key": "string",
      "label": "string",
      "placeholder": "string",
      "required": true,
      "showConditions": [
        {
          "targetKey": "string"
        }
      ],
      "description": "string",
      "tooltip": "string",
      "isConfidential": true
    }
  ],
  "customData": {},
  "fromEmail": "string",
  "platform": "Native",
  "isStandard": true
}

Update connector

PATCH /api/connectors/{id}
O auth2

Update connector by ID with the given data. This methods performs a partial update.

Path parameters

  • id string Required

    The unique identifier of the connector.

application/json

Body Required

  • config object

    The connector config object that will be passed to the connector. The config object should be compatible with the connector factory.

  • metadata object

    Custom connector metadata, will be used to overwrite the default connector metadata.

    Hide metadata attributes Show metadata attributes object
  • syncProfile boolean

    Whether to sync user profile from the identity provider to Logto at each sign-in. If false, the user profile will only be synced when the user is created.

Responses

PATCH /api/connectors/{id} 
curl \
 --request PATCH 'https://[tenant_id].logto.app/api/connectors/{id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"config":{},"metadata":{"target":"string","name":{},"logo":"string","logoDark":"string"},"syncProfile":true}'
Request examples 
{
  "config": {},
  "metadata": {
    "target": "string",
    "name": {},
    "logo": "string",
    "logoDark": "string"
  },
  "syncProfile": true
}
Response examples (200) 
{
  "id": "string",
  "syncProfile": true,
  "config": {},
  "metadata": {
    "target": "string",
    "name": {},
    "logo": "string",
    "logoDark": "string"
  },
  "connectorId": "string",
  "target": "string",
  "name": {},
  "description": {},
  "logo": "string",
  "logoDark": "string",
  "readme": "string",
  "configTemplate": "string",
  "formItems": [
    {
      "type": "string",
      "selectItems": [
        {
          "value": "string",
          "title": "string"
        }
      ],
      "key": "string",
      "label": "string",
      "placeholder": "string",
      "required": true,
      "showConditions": [
        {
          "targetKey": "string"
        }
      ],
      "description": "string",
      "tooltip": "string",
      "isConfidential": true
    }
  ],
  "customData": {},
  "fromEmail": "string",
  "platform": "Native",
  "isStandard": true,
  "type": "Email",
  "isDemo": true,
  "extraInfo": {},
  "usage": 42.0
}

Get custom phrases

GET /api/custom-phrases/{languageTag}
O auth2

Get custom phrases for the specified language tag.

Path parameters

  • languageTag string Required

    Values are 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-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, or zz-TR.

Responses

  • 200 application/json

    Custom phrases for the specified language tag.

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • id string Required

      Minimum length is 1, maximum length is 21.

    • languageTag string Required

      Minimum length is 1, maximum length is 16.

    • translation object Required
      Hide translation attribute Show translation attribute object
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Custom phrases not found.

GET /api/custom-phrases/{languageTag} 
curl \
 --request GET 'https://[tenant_id].logto.app/api/custom-phrases/{languageTag}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "tenantId": "string",
  "id": "string",
  "languageTag": "string",
  "translation": {
    "input": {
      "password": "Password",
      "username": "Username"
    },
    "action": {
      "sign_in": "Sign In",
      "continue": "Continue"
    }
  }
}

Delete custom phrase

DELETE /api/custom-phrases/{languageTag}
O auth2

Delete custom phrases for the specified language tag.

Path parameters

  • languageTag string Required

    Values are 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-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, or zz-TR.

Responses

  • 204

    Custom phrases deleted successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Custom phrases not found.

  • 409

    Cannot delete the default language.

DELETE /api/custom-phrases/{languageTag} 
curl \
 --request DELETE 'https://[tenant_id].logto.app/api/custom-phrases/{languageTag}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Get domains

GET /api/domains
O auth2

Get all of your custom domains.

Responses

  • 200 application/json

    A list of domains.

    Hide response attributes Show response attributes object
    • id string Required

      Minimum length is 1, maximum length is 21.

    • domain string Required

      Minimum length is 1, maximum length is 256.

    • status string Required

      Values are PendingVerification, PendingSsl, Active, or Error.

    • errorMessage string | null Required

      Maximum length is 1024.

    • dnsRecords array[object] Required
      Hide dnsRecords attributes Show dnsRecords attributes object
  • 401

    Unauthorized

  • 403

    Forbidden

GET /api/domains 
curl \
 --request GET 'https://[tenant_id].logto.app/api/domains' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "id": "string",
    "domain": "string",
    "status": "PendingVerification",
    "errorMessage": "string",
    "dnsRecords": [
      {
        "name": "string",
        "type": "string",
        "value": "string"
      }
    ]
  }
]

Delete an email template

DELETE /api/email-templates/{id}
O auth2

Delete an email template by its ID.

Path parameters

  • id string Required

    The unique identifier of the email template.

Responses

  • 204

    The email template was deleted successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    The email template was not found.

DELETE /api/email-templates/{id} 
curl \
 --request DELETE 'https://[tenant_id].logto.app/api/email-templates/{id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Create TOTP secret

POST /api/experience/verification/totp/secret

Create a new TOTP verification record and generate a new TOTP secret for the user. This secret can be used to bind a new TOTP verification to the user's profile. The verification record must be verified before the secret can be used to bind a new TOTP verification to the user's profile.

Responses

  • 200 application/json

    TOTP secret successfully generated.

    Hide response attributes Show response attributes object
    • verificationId string Required

      The unique verification ID for the TOTP record. This ID is required to verify the TOTP code.

    • secret string Required

      The newly generated TOTP secret.

    • secretQrCode string Required

      A QR code image data URL for the TOTP secret. The user can scan this QR code with their TOTP authenticator app.
  • 400

    Bad Request

  • 404

    Entity not found.
    - session.identifier_not_found: The current interaction is not identified yet. All MFA verification records must be associated with a identified user.

POST /api/experience/verification/totp/secret 
curl \
 --request POST 'https://[tenant_id].logto.app/api/experience/verification/totp/secret'
Response examples (200) 
{
  "verificationId": "string",
  "secret": "string",
  "secretQrCode": "string"
}

Generate backup codes

POST /api/experience/verification/backup-code/generate

Create a new BackupCode verification record with new backup codes generated. This verification record will be used to bind the backup codes to the user's profile.

Responses

  • 200 application/json

    Backup codes have been successfully generated.

    Hide response attributes Show response attributes object
    • verificationId string Required

      The unique verification ID of the newly created BackupCode verification record. This ID is required when adding the backup codes to the user profile via the Profile API.

    • codes array[string] Required

      The generated backup codes.
  • 400

    Bad Request

  • 404

    The current interaction is not identified yet. All MFA verification records must be associated with a identified user.

POST /api/experience/verification/backup-code/generate 
curl \
 --request POST 'https://[tenant_id].logto.app/api/experience/verification/backup-code/generate'
Response examples (200) 
{
  "verificationId": "string",
  "codes": [
    "string"
  ]
}

Get recent logs for a hook

GET /api/hooks/{id}/recent-logs
O auth2

Get recent logs that match the given query for the specified hook with pagination.

Path parameters

  • id string Required

    The unique identifier of the hook.

Query parameters

  • logKey string

    The log key to filter logs.

  • page integer

    Page number (starts from 1).

    Minimum value is 1. Default value is 1.

  • page_size integer

    Entries per page.

    Minimum value is 1. Default value is 20.

Responses

GET /api/hooks/{id}/recent-logs 
curl \
 --request GET 'https://[tenant_id].logto.app/api/hooks/{id}/recent-logs' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "id": "string",
    "key": "string",
    "payload": {
      "key": "string",
      "result": "Success",
      "error": {},
      "ip": "string",
      "userAgent": "string",
      "userId": "string",
      "applicationId": "string",
      "sessionId": "string",
      "params": {}
    },
    "createdAt": 42.0
  }
]