From 7fbf51cfaf2ad936f40884022b287945eda25148 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Thu, 11 Sep 2025 15:31:14 +0530 Subject: [PATCH 1/8] fix: first draft --- api_spec.yaml | 342 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 340 insertions(+), 2 deletions(-) diff --git a/api_spec.yaml b/api_spec.yaml index 0c46515..5ab7792 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -7,7 +7,7 @@ info: Those that do not have `` in the path will enforce that the API is called from `public` tenant only. - version: 5.2.0 + version: 5.3.0 title: Core Driver Interface contact: email: team@supertokens.io @@ -7774,7 +7774,7 @@ paths: $ref: '#/components/responses/404' '500': - $ref: '#/components/responses/500' + $ref: '#/components/responses/500' /appid-/recipe/oauth/introspect: post: tags: @@ -7872,6 +7872,317 @@ paths: '500': $ref: '#/components/responses/500' + /appid-//recipe/saml/clients/create: + put: + tags: + - Saml Recipe + description: | + Create or update a SAML client for the specified tenant. + operationId: createOrUpdateSamlClient + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + requestBody: + content: + application/json: + schema: + type: object + properties: + clientId: + type: string + spEntityId: + type: string + redirectURIs: + type: array + items: + type: string + defaultRedirectURI: + type: string + metadataXML: + type: string + required: + - redirectURIs + - defaultRedirectURI + - metadataXML + responses: + '200': + description: Returns the created or updated SAML client + content: + application/json: + schema: + $ref: '#/components/schemas/samlClient' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + + /appid-//recipe/saml/clients/list: + get: + tags: + - Saml Recipe + description: | + Get the list of all SAML clients configured for the specified tenant. + operationId: listSamlClients + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + responses: + '200': + description: Returns all SAML clients + content: + application/json: + schema: + type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + clients: + type: array + items: + $ref: '#/components/schemas/samlClient' + required: + - status + - clients + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + + /appid-//recipe/saml/clients/remove: + post: + tags: + - Saml Recipe + description: | + Delete a SAML client for the specified tenant. + operationId: removeSamlClient + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + requestBody: + content: + application/json: + schema: + type: object + properties: + clientId: + type: string + required: + - clientId + responses: + '200': + description: Indicates whether the client existed + content: + application/json: + schema: + type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + didExist: + type: boolean + required: + - status + - didExist + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + + /appid-//recipe/saml/login: + post: + tags: + - Saml Recipe + description: | + Create a new login redirect URL for a given SAML client ID. + operationId: createSamlLoginRedirect + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + requestBody: + content: + application/json: + schema: + type: object + properties: + clientId: + type: string + redirectURI: + type: string + required: + - clientId + - redirectURI + responses: + '200': + description: Returns the URL to redirect the user to the IdP + content: + application/json: + schema: + oneOf: + - type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + ssoRedirectURI: + type: string + required: + - status + - ssoRedirectURI + - type: object + properties: + status: + type: string + enum: ['INVALID_CLIENT_ERROR'] + required: + - status + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + + /appid-//recipe/saml/callback: + post: + tags: + - Saml Recipe + description: | + Handle the SAML response from the Identity Provider (IdP). + operationId: handleSamlCallback + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + requestBody: + content: + application/json: + schema: + type: object + properties: + samlResponse: + type: string + relayState: + type: string + required: + - samlResponse + responses: + '200': + description: Returns an intermediate code on success + content: + application/json: + schema: + oneOf: + - type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + code: + type: string + required: + - status + - code + - type: object + properties: + status: + type: string + enum: ['INVALID_SAML_RESPONSE_ERROR'] + message: + type: string + required: + - status + - message + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + + /appid-//recipe/saml/token: + post: + tags: + - Saml Recipe + description: | + Exchange an intermediate code for tokens and user claims. + operationId: exchangeSamlCode + parameters: + - $ref: '#/components/parameters/samlRid' + - $ref: '#/components/parameters/api-key' + - $ref: '#/components/parameters/cdi-version' + requestBody: + content: + application/json: + schema: + type: object + properties: + code: + type: string + required: + - code + responses: + '200': + description: Returns tokens and claims on success + content: + application/json: + schema: + oneOf: + - type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + tokens: + type: object + properties: + accessToken: + type: string + idToken: + type: string + required: + - accessToken + - idToken + claims: + type: object + additionalProperties: + type: string + required: + - status + - tokens + - claims + - type: object + properties: + status: + type: string + enum: ['INVALID_CODE_ERROR'] + required: + - status + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + components: parameters: @@ -7928,6 +8239,13 @@ components: required: false schema: type: string + samlRid: + name: rid + in: header + example: saml + required: false + schema: + type: string userMetadataRid: name: rid in: header @@ -8398,6 +8716,26 @@ components: type: boolean example: false + samlClient: + type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + clientId: + type: string + spEntityId: + type: string + redirectURIs: + type: array + items: + type: string + defaultRedirectURI: + type: string + required: + - clientId + - redirectURIs + - defaultRedirectURI + userMetadata: type: object description: should be a JSON object (not a JSON literal nor an array) From 676998c63dbf7e3b726f8f3f894c9863605a20fa Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Thu, 25 Sep 2025 12:08:58 +0530 Subject: [PATCH 2/8] fix: create or update saml client --- api_spec.yaml | 56 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/api_spec.yaml b/api_spec.yaml index c36f3f1..ab0fcf1 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -8024,7 +8024,7 @@ paths: $ref: '#/components/responses/404' '500': - $ref: '#/components/responses/500' + $ref: '#/components/responses/500' /appid-/recipe/oauth/introspect: post: tags: @@ -8124,7 +8124,7 @@ paths: '500': $ref: '#/components/responses/500' - /appid-//recipe/saml/clients/create: + /appid-//recipe/saml/clients: put: tags: - Saml Recipe @@ -8153,17 +8153,36 @@ paths: type: string metadataXML: type: string + metadataURL: + type: string required: + - spEntityId - redirectURIs - defaultRedirectURI - - metadataXML responses: '200': description: Returns the created or updated SAML client content: application/json: schema: - $ref: '#/components/schemas/samlClient' + oneOf: + - allOf: + - type: object + properties: + status: + $ref: '#/components/schemas/statusOK' + required: + - status + + - $ref: '#/components/schemas/samlClient' + - type: object + properties: + status: + type: string + enum: ["INVALID_METADATA_XML_ERROR"] + example: INVALID_METADATA_XML_ERROR + required: + - status '400': $ref: '#/components/responses/400' '401': @@ -8276,9 +8295,14 @@ paths: type: string redirectURI: type: string + acsURL: + type: string + state: + type: string required: - clientId - redirectURI + - acsURL responses: '200': description: Returns the URL to redirect the user to the IdP @@ -8328,6 +8352,8 @@ paths: schema: type: object properties: + clientId: + type: string samlResponse: type: string relayState: @@ -8345,16 +8371,16 @@ paths: properties: status: $ref: '#/components/schemas/statusOK' - code: + redirectURI: type: string required: - status - - code + - redirectURI - type: object properties: status: type: string - enum: ['INVALID_SAML_RESPONSE_ERROR'] + enum: ['INVALID_CLIENT_ERROR', 'INVALID_RESPONSE_ERROR'] message: type: string required: @@ -8404,21 +8430,13 @@ paths: tokens: type: object properties: - accessToken: - type: string idToken: type: string required: - - accessToken - idToken - claims: - type: object - additionalProperties: - type: string required: - status - tokens - - claims - type: object properties: status: @@ -10135,8 +10153,6 @@ components: samlClient: type: object properties: - status: - $ref: '#/components/schemas/statusOK' clientId: type: string spEntityId: @@ -10147,10 +10163,16 @@ components: type: string defaultRedirectURI: type: string + idpEntityId: + type: string + idpSigningCertificate: + type: string required: - clientId + - spEntityId - redirectURIs - defaultRedirectURI + - idpEntityId userMetadata: type: object From 17e2b3e9a939e93859eac6a5fd0b207d0521700e Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Fri, 26 Sep 2025 12:52:48 +0530 Subject: [PATCH 3/8] fix: idp initiated flow --- api_spec.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api_spec.yaml b/api_spec.yaml index ab0fcf1..64cc3ae 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -8155,6 +8155,8 @@ paths: type: string metadataURL: type: string + allowIDPInitiatedLogin: + type: boolean required: - spEntityId - redirectURIs @@ -10167,12 +10169,15 @@ components: type: string idpSigningCertificate: type: string + allowIDPInitiatedLogin: + type: boolean required: - clientId - spEntityId - redirectURIs - defaultRedirectURI - idpEntityId + - allowIDPInitiatedLogin userMetadata: type: object From 6e3fe9a712df1efd9ad5cdf9b096456ce4437470 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Mon, 29 Sep 2025 17:16:47 +0530 Subject: [PATCH 4/8] fix: callback --- api_spec.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/api_spec.yaml b/api_spec.yaml index 64cc3ae..0a800a6 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -8354,8 +8354,6 @@ paths: schema: type: object properties: - clientId: - type: string samlResponse: type: string relayState: @@ -8382,7 +8380,7 @@ paths: properties: status: type: string - enum: ['INVALID_CLIENT_ERROR', 'INVALID_RESPONSE_ERROR'] + enum: ['INVALID_RELAY_STATE_ERROR', 'SAML_RESPONSE_VERIFICATION_FAILED_ERROR'] message: type: string required: From 0bd6ec39e296077cc79300edc07e1d998a904241 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Tue, 30 Sep 2025 13:17:58 +0530 Subject: [PATCH 5/8] fix: idp flow --- api_spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api_spec.yaml b/api_spec.yaml index 0a800a6..afe72c7 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -8380,7 +8380,7 @@ paths: properties: status: type: string - enum: ['INVALID_RELAY_STATE_ERROR', 'SAML_RESPONSE_VERIFICATION_FAILED_ERROR'] + enum: ['INVALID_RELAY_STATE_ERROR', 'SAML_RESPONSE_VERIFICATION_FAILED_ERROR', 'INVALID_CLIENT_ERROR', 'IDP_LOGIN_DISALLOWED_ERROR'] message: type: string required: From ce9c5c759a7c108c0270bd7f0e71dc2aae6a4541 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Thu, 20 Nov 2025 11:01:26 +0530 Subject: [PATCH 6/8] fix: updates --- api_spec.yaml | 74 ++++++++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 33 deletions(-) diff --git a/api_spec.yaml b/api_spec.yaml index afe72c7..90904e8 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -28,6 +28,7 @@ tags: - name: WebAuthn Recipe - name: JWT Recipe - name: Bulk Import + - name: SAML Recipe paths: @@ -8127,7 +8128,7 @@ paths: /appid-//recipe/saml/clients: put: tags: - - Saml Recipe + - SAML Recipe description: | Create or update a SAML client for the specified tenant. operationId: createOrUpdateSamlClient @@ -8143,7 +8144,7 @@ paths: properties: clientId: type: string - spEntityId: + clientSecret: type: string redirectURIs: type: array @@ -8153,14 +8154,13 @@ paths: type: string metadataXML: type: string - metadataURL: - type: string allowIDPInitiatedLogin: type: boolean + enableRequestSigning: + type: boolean required: - - spEntityId - redirectURIs - - defaultRedirectURI + - metadataXML responses: '200': description: Returns the created or updated SAML client @@ -8181,7 +8181,7 @@ paths: properties: status: type: string - enum: ["INVALID_METADATA_XML_ERROR"] + enum: ["DUPLICATE_IDP_ENTITY_ERROR"] example: INVALID_METADATA_XML_ERROR required: - status @@ -8197,7 +8197,7 @@ paths: /appid-//recipe/saml/clients/list: get: tags: - - Saml Recipe + - SAML Recipe description: | Get the list of all SAML clients configured for the specified tenant. operationId: listSamlClients @@ -8234,7 +8234,7 @@ paths: /appid-//recipe/saml/clients/remove: post: tags: - - Saml Recipe + - SAML Recipe description: | Delete a SAML client for the specified tenant. operationId: removeSamlClient @@ -8279,7 +8279,7 @@ paths: /appid-//recipe/saml/login: post: tags: - - Saml Recipe + - SAML Recipe description: | Create a new login redirect URL for a given SAML client ID. operationId: createSamlLoginRedirect @@ -8340,7 +8340,7 @@ paths: /appid-//recipe/saml/callback: post: tags: - - Saml Recipe + - SAML Recipe description: | Handle the SAML response from the Identity Provider (IdP). operationId: handleSamlCallback @@ -8395,13 +8395,13 @@ paths: '500': $ref: '#/components/responses/500' - /appid-//recipe/saml/token: + /appid-//recipe/saml/user: post: tags: - - Saml Recipe + - SAML Recipe description: | - Exchange an intermediate code for tokens and user claims. - operationId: exchangeSamlCode + Get user information using an access token. + operationId: getSamlUserInfo parameters: - $ref: '#/components/parameters/samlRid' - $ref: '#/components/parameters/api-key' @@ -8412,13 +8412,16 @@ paths: schema: type: object properties: - code: + accessToken: + type: string + clientId: type: string required: - - code + - accessToken + - clientId responses: '200': - description: Returns tokens and claims on success + description: Returns user information on success content: application/json: schema: @@ -8427,21 +8430,24 @@ paths: properties: status: $ref: '#/components/schemas/statusOK' - tokens: + sub: + type: string + email: + type: string + aud: + type: string + claims: type: object - properties: - idToken: - type: string - required: - - idToken required: - status - - tokens + - sub + - email + - claims - type: object properties: status: type: string - enum: ['INVALID_CODE_ERROR'] + enum: ['INVALID_TOKEN_ERROR'] required: - status '400': @@ -10155,27 +10161,29 @@ components: properties: clientId: type: string - spEntityId: + clientSecret: + type: string + defaultRedirectURI: type: string redirectURIs: type: array items: type: string - defaultRedirectURI: - type: string idpEntityId: type: string idpSigningCertificate: type: string allowIDPInitiatedLogin: type: boolean + enableRequestSigning: + type: boolean required: - clientId - - spEntityId - - redirectURIs - defaultRedirectURI + - redirectURIs - idpEntityId - allowIDPInitiatedLogin + - enableRequestSigning userMetadata: type: object @@ -10517,13 +10525,13 @@ components: type: object properties: firstFactors: + nullable: true oneOf: - $ref: '#/components/schemas/firstFactors' - - type: "null" requiredSecondaryFactors: + nullable: true oneOf: - $ref: '#/components/schemas/requiredSecondaryFactors' - - type: "null" coreConfig: type: object From 2bc6660c4717fc65be710fbb630d71cb83874862 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Thu, 20 Nov 2025 11:07:31 +0530 Subject: [PATCH 7/8] fix: cdi version example update --- api_spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api_spec.yaml b/api_spec.yaml index 90904e8..4f4426d 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -9699,7 +9699,7 @@ components: name: cdi-version in: header description: X.Y of the X.Y.Z CDI version. - example: '5.2' + example: '5.3' schema: type: string From fc1a78c50de89480f98fa7b88ca1ea95f102d243 Mon Sep 17 00:00:00 2001 From: Sattvik Chakravarthy Date: Thu, 20 Nov 2025 11:17:48 +0530 Subject: [PATCH 8/8] fix: update version and changelog --- CHANGELOG.md | 10 ++++++++++ api_spec.yaml | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d6ff11..0056933 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [unreleased] +## [5.4.0] + +- Adds SAML related APIs: + - PUT `/appid-//recipe/saml/clients` + - GET `/appid-//recipe/saml/clients/list` + - POST `/appid-//recipe/saml/clients/remove` + - POST `/appid-//recipe/saml/login` + - POST `/appid-//recipe/saml/callback` + - POST `/appid-//recipe/saml/user` + ## [5.3.1] - Fixes various type and path errors in the spec diff --git a/api_spec.yaml b/api_spec.yaml index 4f4426d..f792dad 100644 --- a/api_spec.yaml +++ b/api_spec.yaml @@ -7,7 +7,7 @@ info: Those that do not have `` in the path will enforce that the API is called from `public` tenant only. - version: 5.3.0 + version: 5.4.0 title: Core Driver Interface contact: email: team@supertokens.io @@ -9699,7 +9699,7 @@ components: name: cdi-version in: header description: X.Y of the X.Y.Z CDI version. - example: '5.3' + example: '5.4' schema: type: string