SAML (Security Assertion Markup Language) applications represent applications that use SAML protocol for single sign-on (SSO). These endpoints allow you to manage SAML applications, including their configurations and signing certificates.
openapi: 3.0.1
info:
title: Logto API references Account center SAML applications 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: SAML applications
description: SAML (Security Assertion Markup Language) applications represent applications that use SAML protocol for single sign-on (SSO). These endpoints allow you to manage SAML applications, including their configurations and signing certificates.
paths:
/api/saml-applications:
post:
operationId: CreateSamlApplication
tags:
- SAML applications
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- nameIdFormat
properties:
name:
type: string
minLength: 1
maxLength: 256
description: The name of the SAML application.
description:
type: string
nullable: true
description: Optional description of the SAML application.
customData:
type: object
description: Optional custom data for the application.
attributeMapping:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
email:
type: string
email_verified:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
phone_number:
type: string
phone_number_verified:
type: string
address:
type: string
updated_at:
type: string
username:
type: string
created_at:
type: string
custom_data:
type: string
identities:
type: string
sso_identities:
type: string
roles:
type: string
organizations:
type: string
organization_data:
type: string
organization_roles:
type: string
entityId:
type: string
maxLength: 128
nullable: true
acsUrl:
type: string
required:
- binding
- url
properties:
binding:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
url:
type: string
format: url
nullable: true
description: The Assertion Consumer Service (ACS) URL where the SAML response will be sent.
encryption:
type: object
description: Validator function
nullable: true
nameIdFormat:
default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
responses:
'201':
description: The SAML application was created successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- customData
- isThirdParty
- createdAt
- attributeMapping
- entityId
- acsUrl
- encryption
- nameIdFormat
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description:
type: string
nullable: true
type:
type: string
enum:
- Native
- SPA
- Traditional
- MachineToMachine
- Protected
- SAML
customData:
type: object
description: arbitrary
isThirdParty:
type: boolean
createdAt:
type: number
attributeMapping:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
email:
type: string
email_verified:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
phone_number:
type: string
phone_number_verified:
type: string
address:
type: string
updated_at:
type: string
username:
type: string
created_at:
type: string
custom_data:
type: string
identities:
type: string
sso_identities:
type: string
roles:
type: string
organizations:
type: string
organization_data:
type: string
organization_roles:
type: string
entityId:
type: string
maxLength: 128
nullable: true
acsUrl:
type: object
required:
- binding
- url
properties:
binding:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
url:
type: string
format: url
nullable: true
encryption:
type: object
description: Validator function
nullable: true
nameIdFormat:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
'400':
description: Invalid request body.
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error. The ACS URL is invalid or other validation errors.
summary: Create SAML application
description: Create a new SAML application with the given configuration. A default signing certificate with 3 years lifetime will be automatically created.
/api/saml-applications/{id}:
get:
operationId: GetSamlApplication
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
responses:
'200':
description: The SAML application details.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- customData
- isThirdParty
- createdAt
- attributeMapping
- entityId
- acsUrl
- encryption
- nameIdFormat
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description:
type: string
nullable: true
type:
type: string
enum:
- Native
- SPA
- Traditional
- MachineToMachine
- Protected
- SAML
customData:
type: object
description: arbitrary
isThirdParty:
type: boolean
createdAt:
type: number
attributeMapping:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
email:
type: string
email_verified:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
phone_number:
type: string
phone_number_verified:
type: string
address:
type: string
updated_at:
type: string
username:
type: string
created_at:
type: string
custom_data:
type: string
identities:
type: string
sso_identities:
type: string
roles:
type: string
organizations:
type: string
organization_data:
type: string
organization_roles:
type: string
entityId:
type: string
maxLength: 128
nullable: true
acsUrl:
type: object
required:
- binding
- url
properties:
binding:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
url:
type: string
format: url
nullable: true
encryption:
type: object
description: Validator function
nullable: true
nameIdFormat:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application was not found.
'422':
description: Unprocessable Content
summary: Get SAML application
description: Get SAML application details by ID.
patch:
operationId: UpdateSamlApplication
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 256
description: The name of the SAML application.
description:
type: string
nullable: true
description: Description of the SAML application.
customData:
type: object
description: Custom data for the application.
attributeMapping:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
email:
type: string
email_verified:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
phone_number:
type: string
phone_number_verified:
type: string
address:
type: string
updated_at:
type: string
username:
type: string
created_at:
type: string
custom_data:
type: string
identities:
type: string
sso_identities:
type: string
roles:
type: string
organizations:
type: string
organization_data:
type: string
organization_roles:
type: string
entityId:
type: string
maxLength: 128
nullable: true
acsUrl:
type: string
required:
- binding
- url
properties:
binding:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
url:
type: string
format: url
nullable: true
description: The Assertion Consumer Service (ACS) URL.
encryption:
type: object
description: Validator function
nullable: true
nameIdFormat:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
responses:
'200':
description: The SAML application was updated successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- description
- type
- customData
- isThirdParty
- createdAt
- attributeMapping
- entityId
- acsUrl
- encryption
- nameIdFormat
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description:
type: string
nullable: true
type:
type: string
enum:
- Native
- SPA
- Traditional
- MachineToMachine
- Protected
- SAML
customData:
type: object
description: arbitrary
isThirdParty:
type: boolean
createdAt:
type: number
attributeMapping:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
email:
type: string
email_verified:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
phone_number:
type: string
phone_number_verified:
type: string
address:
type: string
updated_at:
type: string
username:
type: string
created_at:
type: string
custom_data:
type: string
identities:
type: string
sso_identities:
type: string
roles:
type: string
organizations:
type: string
organization_data:
type: string
organization_roles:
type: string
entityId:
type: string
maxLength: 128
nullable: true
acsUrl:
type: object
required:
- binding
- url
properties:
binding:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
url:
type: string
format: url
nullable: true
encryption:
type: object
description: Validator function
nullable: true
nameIdFormat:
type: string
enum:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application was not found.
'422':
description: Validation error.
summary: Update SAML application
description: Update SAML application details by ID.
delete:
operationId: DeleteSamlApplication
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
responses:
'204':
description: The SAML application was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application was not found.
'422':
description: The specified application is not a SAML application.
summary: Delete SAML application
description: Delete a SAML application by ID.
/api/saml-applications/{id}/secrets:
post:
operationId: CreateSamlApplicationSecret
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- lifeSpanInYears
properties:
lifeSpanInYears:
type: integer
minimum: 1
description: The lifetime of the certificate in years (minimum 1 year).
responses:
'201':
description: The signing certificate was created successfully.
content:
application/json:
schema:
type: object
required:
- id
- certificate
- createdAt
- expiresAt
- active
- fingerprints
properties:
id:
type: string
minLength: 1
maxLength: 21
certificate:
type: string
minLength: 1
createdAt:
type: number
expiresAt:
type: number
active:
type: boolean
fingerprints:
type: object
required:
- sha256
properties:
sha256:
type: object
required:
- formatted
- unformatted
properties:
formatted:
type: string
unformatted:
type: string
'400':
description: Invalid request body.
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application was not found.
summary: Create SAML application secret
description: Create a new signing certificate for the SAML application.
get:
operationId: ListSamlApplicationSecrets
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
responses:
'200':
description: A list of signing certificates.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- certificate
- createdAt
- expiresAt
- active
- fingerprints
properties:
id:
type: string
minLength: 1
maxLength: 21
description: The ID of the signing certificate.
certificate:
type: string
minLength: 1
description: The X.509 certificate in PEM format.
createdAt:
type: number
expiresAt:
type: string
format: date-time
description: The expiration time of the certificate.
active:
type: boolean
fingerprints:
type: object
required:
- sha256
properties:
sha256:
type: object
required:
- formatted
- unformatted
properties:
formatted:
type: string
unformatted:
type: string
fingerprint:
type: string
description: The SHA-256 fingerprint of the certificate.
isActive:
type: boolean
description: Whether this certificate is currently active.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application was not found.
summary: List SAML application secrets
description: Get all signing certificates of the SAML application.
/api/saml-applications/{id}/secrets/{secretId}:
delete:
operationId: DeleteSamlApplicationSecret
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
- $ref: '#/components/parameters/secretId'
responses:
'204':
description: The signing certificate was deleted successfully.
'400':
description: Cannot delete an active certificate.
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The SAML application or certificate was not found.
summary: Delete SAML application secret
description: Delete a signing certificate of the SAML application. Active certificates cannot be deleted.
patch:
operationId: UpdateSamlApplicationSecret
tags:
- SAML applications
parameters:
- $ref: '#/components/parameters/samlApplicationId-root'
- $ref: '#/components/parameters/secretId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- active
properties:
active:
type: boolean
description: Whether the certificate is active.
responses:
'200':
description: The signing certificate was updated successfully.
content:
application/json:
schema:
type: object
required:
- id
- certificate
- createdAt
- expiresAt
- active
- fingerprints
properties:
id:
type: string
minLength: 1
maxLength: 21
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-saml-applications-api-openapi.yml