Logto Management API

Connectors

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.

Delete connector

DELETE /api/connectors/{id}
OAuth2

Delete connector by ID.

Path parameters

  • id string Required

    The unique identifier of the connector.

Responses

  • 204

    The connector has been successfully deleted.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Connector not found.

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

Get active user data

GET /api/dashboard/users/active
OAuth2

Get active user data, including daily active user (DAU), weekly active user (WAU) and monthly active user (MAU). It also includes an array of DAU in the past 30 days.

Query parameters

  • date string(regex)

    The date to get active user data.

    Format should match the following pattern: /^\d{4}(-\d{2}){2}/.

Responses

  • 200 application/json

    Active user data object.

    Hide response attributes Show response attributes object
    • dauCurve array[object] Required
      Hide dauCurve attributes Show dauCurve attributes object
      • date string Required
      • count number Required
    • dau object Required
      Hide dau attributes Show dau attributes object
      • count number Required
      • delta number Required
    • wau object Required
      Hide wau attributes Show wau attributes object
      • count number Required
      • delta number Required
    • mau object Required
      Hide mau attributes Show mau attributes object
      • count number Required
      • delta number Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

GET /api/dashboard/users/active 
curl \
 --request GET 'https://[tenant_id].logto.app/api/dashboard/users/active' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "dauCurve": [
    {
      "date": "string",
      "count": 42.0
    }
  ],
  "dau": {
    "count": 42.0,
    "delta": 42.0
  },
  "wau": {
    "count": 42.0,
    "delta": 42.0
  },
  "mau": {
    "count": 42.0,
    "delta": 42.0
  }
}

Create organization invitation

POST /api/organization-invitations
OAuth2

Create an organization invitation and optionally send it via email. The tenant should have an email connector configured if you want to send the invitation via email at this point.

application/json

Body Required

The organization invitation to create.

  • inviterId string | null

    The ID of the user who is inviting the user to join the organization.

    Maximum length is 21.

  • invitee string(email) Required

    The email address of the user to invite to join the organization.

  • organizationId string Required

    The ID of the organization to invite the user to join.

    Minimum length is 1, maximum length is 21.

  • expiresAt number Required

    The epoch time in milliseconds when the invitation expires.

  • organizationRoleIds array[string]

    The IDs of the organization roles to assign to the user when they accept the invitation.

  • messagePayload object | boolean(false) Required

    The message payload for the "OrganizationInvitation" template to use when sending the invitation via email. If it is false, the invitation will not be sent via email.

    One of:
    object-2 object boolean-2 boolean(false)
    Hide attributes Show attributes
    • code string
    • link string
    • Additional properties
    • key string

Responses

  • 201 application/json

    The organization invitation was created successfully.

    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.

    • inviterId string | null Required

      Maximum length is 21.

    • invitee string Required

      Minimum length is 1, maximum length is 256.

    • acceptedUserId string | null Required

      Maximum length is 21.

    • organizationId string Required

      Minimum length is 1, maximum length is 21.

    • status string Required

      Values are Pending, Accepted, Expired, or Revoked.

    • createdAt number Required
    • updatedAt number Required
    • expiresAt number Required
    • organizationRoles array[object] Required
      Hide organizationRoles attributes Show organizationRoles attributes object
      • id string Required
      • name string Required
  • 400

    The organization invitation could not be created. This can happen if the input is invalid or if the expiration date is in the past.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    Unprocessable Content

  • 501

    No email connector is configured for the tenant.

POST /api/organization-invitations 
curl \
 --request POST 'https://[tenant_id].logto.app/api/organization-invitations' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"inviterId":"string","invitee":"hello@example.com","organizationId":"string","expiresAt":42.0,"organizationRoleIds":["string"],"messagePayload":{"code":"string","link":"string","key":"string"}}'
Request examples 
{
  "inviterId": "string",
  "invitee": "hello@example.com",
  "organizationId": "string",
  "expiresAt": 42.0,
  "organizationRoleIds": [
    "string"
  ],
  "messagePayload": {
    "code": "string",
    "link": "string",
    "key": "string"
  }
}
Response examples (201) 
{
  "tenantId": "string",
  "id": "string",
  "inviterId": "string",
  "invitee": "string",
  "acceptedUserId": "string",
  "organizationId": "string",
  "status": "Pending",
  "createdAt": 42.0,
  "updatedAt": 42.0,
  "expiresAt": 42.0,
  "organizationRoles": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Create an organization

POST /api/organizations
OAuth2

Create a new organization with the given data.

application/json

Body Required

  • tenantId string

    Maximum length is 21.

  • name string Required

    The name of the organization.

    Minimum length is 1, maximum length is 128.

  • description string | null

    The description of the organization.

    Maximum length is 256.

  • customData object

    arbitrary

  • isMfaRequired boolean
  • branding object
    Hide branding attributes Show branding attributes object
    • logoUrl string(url)
    • darkLogoUrl string(url)
    • favicon string(url)
    • darkFavicon string(url)
  • createdAt number

Responses

  • 201 application/json

    The organization was created successfully.

    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.

    • name string Required

      Minimum length is 1, maximum length is 128.

    • description string | null Required

      Maximum length is 256.

    • customData object Required

      arbitrary

    • isMfaRequired boolean Required
    • branding object Required
      Hide branding attributes Show branding attributes object
      • logoUrl string(url)
      • darkLogoUrl string(url)
      • favicon string(url)
      • darkFavicon string(url)
    • createdAt number Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

POST /api/organizations 
curl \
 --request POST 'https://[tenant_id].logto.app/api/organizations' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"tenantId":"string","name":"string","description":"string","customData":{},"isMfaRequired":true,"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"createdAt":42.0}'
Request examples 
{
  "tenantId": "string",
  "name": "string",
  "description": "string",
  "customData": {},
  "isMfaRequired": true,
  "branding": {
    "logoUrl": "string",
    "darkLogoUrl": "string",
    "favicon": "string",
    "darkFavicon": "string"
  },
  "createdAt": 42.0
}
Response examples (201) 
{
  "tenantId": "string",
  "id": "string",
  "name": "string",
  "description": "string",
  "customData": {},
  "isMfaRequired": true,
  "branding": {
    "logoUrl": "string",
    "darkLogoUrl": "string",
    "favicon": "string",
    "darkFavicon": "string"
  },
  "createdAt": 42.0
}

Delete organization

DELETE /api/organizations/{id}
OAuth2

Delete organization by ID.

Path parameters

  • id string Required

    The unique identifier of the organization.

Responses

  • 204

    The organization was deleted successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

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

Remove a role from a user in an organization

DELETE /api/organizations/{id}/users/{userId}/roles/{organizationRoleId}
OAuth2

Remove a role assignment from a user in the specified organization.

Path parameters

  • id string Required

    The unique identifier of the organization.

  • userId string Required

    The unique identifier of the user.

  • organizationRoleId string Required

    The unique identifier of the organization role.

Responses

  • 204

    The role was removed from the user successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Cannot find the record to delete.

  • 422

    The user is not a member of the organization.

DELETE /api/organizations/{id}/users/{userId}/roles/{organizationRoleId} 
curl \
 --request DELETE 'https://[tenant_id].logto.app/api/organizations/{id}/users/{userId}/roles/{organizationRoleId}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Get organization applications

GET /api/organizations/{id}/applications
OAuth2

Get applications associated with the organization.

Path parameters

  • id string Required

    The unique identifier of the organization.

Query parameters

  • q string
  • 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

  • 200 application/json

    A list of applications.

    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.

    • name string Required

      Minimum length is 1, maximum length is 256.

    • secret string Required Deprecated

      The internal client secret. Note it is only used for internal validation, and the actual secrets should be retrieved from /api/applications/{id}/secrets endpoints.

    • description string | null Required
    • type string Required

      Values are Native, SPA, Traditional, MachineToMachine, or Protected.

    • oidcClientMetadata object Required
      Hide oidcClientMetadata attributes Show oidcClientMetadata attributes object
      • redirectUris array[object] Required
        One of:
        object-1 object object-2 object

        Validator function

      • postLogoutRedirectUris array[string(url)] Required
      • backchannelLogoutUri string(url)
      • backchannelLogoutSessionRequired boolean
      • logoUri string
    • customClientMetadata object Required
      Hide customClientMetadata attributes Show customClientMetadata attributes object
      • corsAllowedOrigins array[string]

        Minimum length of each is 1.

      • idTokenTtl number
      • refreshTokenTtl number
      • refreshTokenTtlInDays number
      • tenantId string
      • alwaysIssueRefreshToken boolean
      • rotateRefreshToken boolean
    • protectedAppMetadata object | null Required
      Hide protectedAppMetadata attributes Show protectedAppMetadata attributes object | null
      • host string Required
      • origin string Required
      • sessionDuration number Required
      • pageRules array[object] Required
        Hide pageRules attribute Show pageRules attribute object
        • path string Required
      • customDomains array[object]
        Hide customDomains attributes Show customDomains attributes object
        • domain string Required
        • status string Required

          Values are PendingVerification, PendingSsl, Active, or Error.

        • errorMessage string | null Required
        • dnsRecords array[object] Required
          Hide dnsRecords attributes Show dnsRecords attributes object
          • name string Required
          • type string Required
          • value string Required
        • cloudflareData object | null Required
          Hide cloudflareData attributes Show cloudflareData attributes object | null
          • id string Required
          • status string Required
          • ssl object Required
            Hide ssl attributes Show ssl attributes object
            • status string Required
            • validation_errors array[object]
              Hide validation_errors attribute Show validation_errors attribute object
              • message string Required
          • verification_errors array[string]
    • customData object Required

      arbitrary

    • isThirdParty boolean Required
    • createdAt number Required
    • organizationRoles array[object] Required
      Hide organizationRoles attributes Show organizationRoles attributes object
      • id string Required
      • name string Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

GET /api/organizations/{id}/applications 
curl \
 --request GET 'https://[tenant_id].logto.app/api/organizations/{id}/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,
    "organizationRoles": [
      {
        "id": "string",
        "name": "string"
      }
    ]
  }
]

Replace organization applications

PUT /api/organizations/{id}/applications
OAuth2

Replace all applications associated with the organization with the given data.

Path parameters

  • id string Required

    The unique identifier of the organization.

application/json

Body Required

  • applicationIds array[string] Required

    An array of application IDs to replace existing applications.

    Minimum length of each is 1.

Responses

  • 204

    The applications were replaced successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    The applications could not be replaced. Some of the applications may not exist.

PUT /api/organizations/{id}/applications 
curl \
 --request PUT 'https://[tenant_id].logto.app/api/organizations/{id}/applications' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"applicationIds":["string"]}'
Request examples 
{
  "applicationIds": [
    "string"
  ]
}

Assign roles to applications in an organization

POST /api/organizations/{id}/applications/roles
OAuth2

Assign roles to applications in the specified organization.

Path parameters

  • id string Required

    The unique identifier of the organization.

application/json

Body Required

  • applicationIds array[string] Required

    An array of application IDs to assign roles to.

    Minimum length of each is 1.

  • organizationRoleIds array[string] Required

    An array of organization role IDs to assign to the applications.

    Minimum length of each is 1.

Responses

  • 201 application/json

    Roles were assigned to the applications successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    At least one of the IDs provided is not valid. For example, the organization ID, application ID, or organization role ID does not exist; the application is not a member of the organization; or the role type is not assignable to the application.

POST /api/organizations/{id}/applications/roles 
curl \
 --request POST 'https://[tenant_id].logto.app/api/organizations/{id}/applications/roles' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"applicationIds":["string"],"organizationRoleIds":["string"]}'
Request examples 
{
  "applicationIds": [
    "string"
  ],
  "organizationRoleIds": [
    "string"
  ]
}

Replace organization JIT default roles

PUT /api/organizations/{id}/jit/roles
OAuth2

Replace all organization roles that will be assigned to users during just-in-time provisioning with the given data.

Path parameters

  • id string Required

    The unique identifier of the organization.

application/json

Body Required

  • organizationRoleIds array[string] Required

    An array of organization role IDs to replace existing organization roles.

    Minimum length of each is 1.

Responses

  • 204

    The organization roles were replaced successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    The organization roles could not be replaced. Some of the organization roles may not exist.

PUT /api/organizations/{id}/jit/roles 
curl \
 --request PUT 'https://[tenant_id].logto.app/api/organizations/{id}/jit/roles' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"organizationRoleIds":["string"]}'
Request examples 
{
  "organizationRoleIds": [
    "string"
  ]
}

Add organization JIT default roles

POST /api/organizations/{id}/jit/roles
OAuth2

Add new organization roles that will be assigned to users during just-in-time provisioning.

Path parameters

  • id string Required

    The unique identifier of the organization.

application/json

Body Required

  • organizationRoleIds array[string] Required

    The organization role IDs to add.

    Minimum length of each is 1.

Responses

  • 201 application/json

    The organization roles were added successfully.

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 422

    The organization roles could not be added. Some of the organization roles may not exist.

POST /api/organizations/{id}/jit/roles 
curl \
 --request POST 'https://[tenant_id].logto.app/api/organizations/{id}/jit/roles' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"organizationRoleIds":["string"]}'
Request examples 
{
  "organizationRoleIds": [
    "string"
  ]
}

Get organization JIT SSO connectors

GET /api/organizations/{id}/jit/sso-connectors
OAuth2

Get enterprise SSO connectors for just-in-time provisioning of users in the organization.

Path parameters

  • id string Required

    The unique identifier of the organization.

Query parameters

  • 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

  • 200 application/json

    A list of SSO connectors.

    Hide response attributes Show response attributes object
    • tenantId string Required

      Maximum length is 21.

    • id string Required

      Minimum length is 1, maximum length is 128.

    • providerName string Required

      Minimum length is 1, maximum length is 128.

    • connectorName string Required

      Minimum length is 1, maximum length is 128.

    • config object Required

      arbitrary

    • domains array[string] Required
    • branding object Required
      Hide branding attributes Show branding attributes object
      • displayName string
    • syncProfile boolean Required
    • createdAt number Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

GET /api/organizations/{id}/jit/sso-connectors 
curl \
 --request GET 'https://[tenant_id].logto.app/api/organizations/{id}/jit/sso-connectors' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
[
  {
    "tenantId": "string",
    "id": "string",
    "providerName": "string",
    "connectorName": "string",
    "config": {},
    "domains": [
      "string"
    ],
    "branding": {
      "displayName": "string",
      "logo": "string",
      "darkLogo": "string"
    },
    "syncProfile": true,
    "createdAt": 42.0
  }
]

Get API resource scopes

GET /api/resources/{resourceId}/scopes
OAuth2

Get scopes (permissions) defined for an API resource.

Path parameters

  • resourceId string Required

    The unique identifier of the resource.

Query parameters

  • 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 attributes Show search_params attributes object
    • Additional properties
    • key string

Responses

  • 200 application/json

    An array of scopes for the requested resource.

    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.

    • resourceId string Required

      Minimum length is 1, maximum length is 21.

    • name string Required

      Minimum length is 1, maximum length is 256.

    • description string | null Required
    • createdAt number Required
  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

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

SSO connectors

Endpoints for managing single sign-on (SSO) connectors. Your sign-in experience can use these well-configured SSO connectors to authenticate users and sync user attributes from external identity providers (IdPs).

SSO connectors are created by SSO connector provider factories.