openapi: 3.0.1 info: title: Logto API references Account center Connectors 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: Connectors description: 'Connectors are the bridge between Logto and other third-party vendors who provide short message service (SMS), email service, or user information on wildly accepted social media. To learn more about connectors, please see [🪛 Configure connectors](https://docs.logto.io/docs/recipes/configure-connectors/).' paths: /api/connectors: post: operationId: CreateConnector tags: - Connectors parameters: [] requestBody: required: true content: application/json: schema: type: object required: - connectorId properties: config: type: object description: The connector config object that will be passed to the connector. The config object should be compatible with the connector factory. connectorId: type: string minLength: 1 maxLength: 128 description: The connector factory ID for creating the connector. metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true description: Custom connector metadata, will be used to overwrite the default connector factory metadata. syncProfile: type: boolean description: 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. enableTokenStorage: type: boolean id: type: string minLength: 1 maxLength: 128 description: The unique ID for the connector. If not provided, a random ID will be generated. responses: '200': description: The created connector. content: application/json: schema: type: object required: - id - syncProfile - enableTokenStorage - config - metadata - connectorId - target - name - description - logo - logoDark - readme - platform - type properties: id: type: string syncProfile: type: boolean enableTokenStorage: type: boolean config: type: object description: arbitrary metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true connectorId: type: string minLength: 1 maxLength: 128 target: type: string name: type: object description: Validator function description: type: object description: Validator function logo: type: string logoDark: type: string nullable: true readme: type: string configTemplate: type: string formItems: type: array items: oneOf: - type: object required: - type - selectItems - key - label properties: type: type: string format: '"Select"' selectItems: type: array items: type: object required: - value - title properties: value: type: string title: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - selectItems - key - label properties: type: type: string format: '"MultiSelect"' selectItems: type: array items: type: object required: - value properties: value: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - key - label properties: type: type: string enum: - Text - Number - MultilineText - Switch - Json key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean customData: type: object additionalProperties: example: {} fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean type: type: string enum: - Email - Sms - Social isDemo: type: boolean extraInfo: type: object additionalProperties: example: {} usage: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: The tenant has reached the maximum number of connectors. '422': description: Invalid request body. summary: Create connector description: Create a connector with the given data. get: operationId: ListConnectors tags: - Connectors parameters: - name: target in: query required: false schema: type: string description: Filter connectors by target. responses: '200': description: An array of connectors. content: application/json: schema: type: array items: type: object required: - id - syncProfile - enableTokenStorage - config - metadata - connectorId - target - name - description - logo - logoDark - readme - platform - type properties: id: type: string syncProfile: type: boolean enableTokenStorage: type: boolean config: type: object description: arbitrary metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true connectorId: type: string minLength: 1 maxLength: 128 target: type: string name: type: object description: Validator function description: type: object description: Validator function logo: type: string logoDark: type: string nullable: true readme: type: string configTemplate: type: string formItems: type: array items: oneOf: - type: object required: - type - selectItems - key - label properties: type: type: string format: '"Select"' selectItems: type: array items: type: object required: - value - title properties: value: type: string title: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - selectItems - key - label properties: type: type: string format: '"MultiSelect"' selectItems: type: array items: type: object required: - value properties: value: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - key - label properties: type: type: string enum: - Text - Number - MultilineText - Switch - Json key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean customData: type: object additionalProperties: example: {} fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean type: type: string enum: - Email - Sms - Social isDemo: type: boolean extraInfo: type: object additionalProperties: example: {} usage: type: number '400': description: The target only allows one connector to exist, but there are multiple connectors with this target. '401': description: Unauthorized '403': description: Forbidden summary: Get connectors description: Get all connectors in the current tenant. /api/connectors/{id}: get: operationId: GetConnector tags: - Connectors parameters: - $ref: '#/components/parameters/connectorId-root' responses: '200': description: The connector data. content: application/json: schema: type: object required: - id - syncProfile - enableTokenStorage - config - metadata - connectorId - target - name - description - logo - logoDark - readme - platform - type properties: id: type: string syncProfile: type: boolean enableTokenStorage: type: boolean config: type: object description: arbitrary metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true connectorId: type: string minLength: 1 maxLength: 128 target: type: string name: type: object description: Validator function description: type: object description: Validator function logo: type: string logoDark: type: string nullable: true readme: type: string configTemplate: type: string formItems: type: array items: oneOf: - type: object required: - type - selectItems - key - label properties: type: type: string format: '"Select"' selectItems: type: array items: type: object required: - value - title properties: value: type: string title: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - selectItems - key - label properties: type: type: string format: '"MultiSelect"' selectItems: type: array items: type: object required: - value properties: value: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - key - label properties: type: type: string enum: - Text - Number - MultilineText - Switch - Json key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean customData: type: object additionalProperties: example: {} fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean type: type: string enum: - Email - Sms - Social isDemo: type: boolean extraInfo: type: object additionalProperties: example: {} usage: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Connector not found. summary: Get connector description: Get connector data by ID patch: operationId: UpdateConnector tags: - Connectors parameters: - $ref: '#/components/parameters/connectorId-root' requestBody: required: true content: application/json: schema: type: object properties: config: type: object description: The connector config object that will be passed to the connector. The config object should be compatible with the connector factory. metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true description: Custom connector metadata, will be used to overwrite the default connector metadata. syncProfile: type: boolean description: 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. enableTokenStorage: type: boolean responses: '200': description: The updated connector. content: application/json: schema: type: object required: - id - syncProfile - enableTokenStorage - config - metadata - connectorId - target - name - description - logo - logoDark - readme - platform - type properties: id: type: string syncProfile: type: boolean enableTokenStorage: type: boolean config: type: object description: arbitrary metadata: type: object properties: target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true connectorId: type: string minLength: 1 maxLength: 128 target: type: string name: type: object description: Validator function description: type: object description: Validator function logo: type: string logoDark: type: string nullable: true readme: type: string configTemplate: type: string formItems: type: array items: oneOf: - type: object required: - type - selectItems - key - label properties: type: type: string format: '"Select"' selectItems: type: array items: type: object required: - value - title properties: value: type: string title: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - selectItems - key - label properties: type: type: string format: '"MultiSelect"' selectItems: type: array items: type: object required: - value properties: value: type: string key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean - type: object required: - type - key - label properties: type: type: string enum: - Text - Number - MultilineText - Switch - Json key: type: string label: type: string placeholder: type: string required: type: boolean defaultValue: example: {} showConditions: type: array items: type: object required: - targetKey properties: targetKey: type: string expectValue: example: {} description: type: string tooltip: type: string isConfidential: type: boolean isDevFeature: type: boolean customData: type: object additionalProperties: example: {} fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean type: type: string enum: - Email - Sms - Social isDemo: type: boolean extraInfo: type: object additionalProperties: example: {} usage: type: number '400': description: Invalid request body. '401': description: Unauthorized '403': description: Forbidden '404': description: Connector not found. '422': description: Patch operation triggered a connector conflict. summary: Update connector description: Update connector by ID with the given data. This methods performs a partial update. delete: operationId: DeleteConnector tags: - Connectors parameters: - $ref: '#/components/parameters/connectorId-root' responses: '204': description: The connector has been successfully deleted. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Connector not found. summary: Delete connector description: Delete connector by ID. /api/connectors/{factoryId}/test: post: operationId: CreateConnectorTest tags: - Connectors parameters: - $ref: '#/components/parameters/factoryId' requestBody: required: true content: application/json: schema: type: object required: - config properties: phone: type: string format: regex pattern: /^\d+$/ description: Phone number to send test message to. If this is set, email will be ignored. email: type: string format: regex pattern: /^\S+@\S+\.\S+$/ description: Email address to send test message to. If phone is set, this will be ignored. config: type: object description: Connector configuration object for testing. locale: type: string description: Preferred language for the message. If not set, the default language will be used. (Applicable only when custom i18n templates are configured.) responses: '204': description: Test message was sent successfully. '400': description: Invalid request body (e.g. wrong phone number, email or config). '401': description: Unauthorized '403': description: Forbidden '404': description: Connector not found. summary: Test passwordless connector description: Test a passwordless (email or SMS) connector by sending a test message to the given phone number or email address. /api/connectors/{connectorId}/authorization-uri: post: operationId: CreateConnectorAuthorizationUri tags: - Connectors parameters: - $ref: '#/components/parameters/connectorId' requestBody: required: true content: application/json: schema: type: object required: - state - redirectUri properties: state: type: string description: A random string generated on the client side to prevent CSRF (Cross-Site Request Forgery) attacks. redirectUri: type: string description: The URI to navigate back to after the user is authenticated by the connected social identity provider and has granted access to the connector. responses: '200': description: Successfully built authorization URI. content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string format: url redirectUri: description: The URI to navigate for authentication and authorization in the connected social identity provider. '400': description: Unable to build authorization URI. '401': description: Unauthorized '403': description: Forbidden '404': description: The connector with the specified ID does not exist. summary: Get connector's authorization URI description: Get authorization URI for specified connector by providing redirect URI and randomly generated state. components: parameters: connectorId-root: in: path description: The unique identifier of the connector. required: true schema: type: string name: id connectorId: in: path description: The unique identifier of the connector. required: true schema: type: string name: connectorId factoryId: in: path description: The unique identifier of the factory. required: true schema: type: string name: factoryId 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