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.
openapi: 3.0.1
info:
title: Logto API references Account center SSO 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: SSO connectors
description: '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.'
paths:
/api/sso-connectors:
post:
operationId: CreateSsoConnector
tags:
- SSO connectors
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- providerName
- connectorName
properties:
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
enableTokenStorage:
type: boolean
providerName:
type: string
minLength: 1
maxLength: 128
connectorName:
type: string
minLength: 1
maxLength: 128
responses:
'200':
description: The created SSO connector.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- providerName
- connectorName
- config
- domains
- branding
- syncProfile
- enableTokenStorage
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 128
providerName:
type: string
minLength: 1
maxLength: 128
connectorName:
type: string
minLength: 1
maxLength: 128
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
enableTokenStorage:
type: boolean
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: Conflict
'422':
description: At lease one of the given input fields is invalid or IdP connection cannot be verified with the given config.
summary: Create SSO connector
description: Create an new SSO connector instance for a given provider.
get:
operationId: ListSsoConnectors
tags:
- SSO connectors
parameters:
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of SSO connectors.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- providerName
- connectorName
- config
- domains
- branding
- syncProfile
- enableTokenStorage
- createdAt
- name
- providerType
- providerLogo
- providerLogoDark
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 128
providerName:
type: string
enum:
- OIDC
- SAML
- AzureAD
- GoogleWorkspace
- Okta
- AzureAdOidc
connectorName:
type: string
minLength: 1
maxLength: 128
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
enableTokenStorage:
type: boolean
createdAt:
type: number
name:
type: string
providerType:
type: string
enum:
- oidc
- saml
providerLogo:
type: string
providerLogoDark:
type: string
providerConfig:
type: object
additionalProperties:
example: {}
'401':
description: Unauthorized
'403':
description: Forbidden
summary: List SSO connectors
description: Get SSO connectors with pagination. In addition to the raw SSO connector data, a copy of fetched or parsed IdP configs and a copy of connector provider's data will be attached.
/api/sso-connectors/{id}:
get:
operationId: GetSsoConnector
tags:
- SSO connectors
parameters:
- $ref: '#/components/parameters/ssoConnectorId-root'
responses:
'200':
description: The SSO connector data with the given ID.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- providerName
- connectorName
- config
- domains
- branding
- syncProfile
- enableTokenStorage
- createdAt
- name
- providerType
- providerLogo
- providerLogoDark
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 128
providerName:
type: string
enum:
- OIDC
- SAML
- AzureAD
- GoogleWorkspace
- Okta
- AzureAdOidc
connectorName:
type: string
minLength: 1
maxLength: 128
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
enableTokenStorage:
type: boolean
createdAt:
type: number
name:
type: string
providerType:
type: string
enum:
- oidc
- saml
providerLogo:
type: string
providerLogoDark:
type: string
providerConfig:
type: object
additionalProperties:
example: {}
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: SSO connector not found.
summary: Get SSO connector
description: Get SSO connector data by ID. In addition to the raw SSO connector data, a copy of fetched or parsed IdP configs and a copy of connector provider's data will be attached.
delete:
operationId: DeleteSsoConnector
tags:
- SSO connectors
parameters:
- $ref: '#/components/parameters/ssoConnectorId-root'
responses:
'204':
description: SSO connector deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: SSO connector not found.
summary: Delete SSO connector
description: Delete an SSO connector by ID.
patch:
operationId: UpdateSsoConnector
tags:
- SSO connectors
parameters:
- $ref: '#/components/parameters/ssoConnectorId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
connectorName:
type: string
minLength: 1
maxLength: 128
enableTokenStorage:
type: boolean
responses:
'200':
description: The updated SSO connector.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- providerName
- connectorName
- config
- domains
- branding
- syncProfile
- enableTokenStorage
- createdAt
- name
- providerType
- providerLogo
- providerLogoDark
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 128
providerName:
type: string
enum:
- OIDC
- SAML
- AzureAD
- GoogleWorkspace
- Okta
- AzureAdOidc
connectorName:
type: string
minLength: 1
maxLength: 128
config:
type: object
description: arbitrary
domains:
type: array
items:
type: string
branding:
type: object
properties:
displayName:
type: string
logo:
type: string
darkLogo:
type: string
syncProfile:
type: boolean
enableTokenStorage:
type: boolean
createdAt:
type: number
name:
type: string
providerType:
type: string
enum:
- oidc
- saml
providerLogo:
type: string
providerLogoDark:
type: string
providerConfig:
type: object
additionalProperties:
example: {}
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: SSO connector not found.
'409':
description: Conflict
'422':
description: At lease one of the update fields is invalid or IdP connection can not be verified with the given connection config.
summary: Update SSO connector
description: Update an SSO connector by ID. This method performs a partial update.
components:
parameters:
ssoConnectorId-root:
in: path
description: The unique identifier of the sso connector.
required: true
schema:
type: string
name: id
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