From 54232a4c4d5d0000cc45a81843041ace1f0333c8 Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Thu, 7 May 2026 15:44:21 -0700 Subject: [PATCH 1/2] Add passkey credentialId to auth credential list --- mintlify/openapi.yaml | 111 +++++++++++++++--- openapi.yaml | 111 +++++++++++++++--- .../schemas/auth/AuthCredentialListItem.yaml | 16 +++ .../auth/AuthCredentialListResponse.yaml | 2 +- .../components/schemas/auth/AuthMethod.yaml | 47 ++------ .../schemas/auth/AuthMethodBase.yaml | 36 ++++++ .../schemas/auth/EmailOtpAuthMethod.yaml | 14 +++ .../schemas/auth/OauthAuthMethod.yaml | 13 ++ .../schemas/auth/PasskeyAuthMethod.yaml | 25 ++++ openapi/paths/auth/auth_credentials.yaml | 9 +- 10 files changed, 311 insertions(+), 73 deletions(-) create mode 100644 openapi/components/schemas/auth/AuthCredentialListItem.yaml create mode 100644 openapi/components/schemas/auth/AuthMethodBase.yaml create mode 100644 openapi/components/schemas/auth/EmailOtpAuthMethod.yaml create mode 100644 openapi/components/schemas/auth/OauthAuthMethod.yaml create mode 100644 openapi/components/schemas/auth/PasskeyAuthMethod.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index dcadafc8..eaffc32e 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -3910,7 +3910,7 @@ paths: $ref: '#/components/schemas/AuthCredentialListResponse' examples: multipleCredentials: - summary: Internal account with an email OTP and a passkey credential + summary: Internal account with multiple authentication credentials value: data: - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 @@ -3919,9 +3919,16 @@ paths: nickname: example@lightspark.com createdAt: '2026-04-08T15:30:01Z' updatedAt: '2026-04-08T15:30:01Z' + - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000004 + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: OAUTH + nickname: example@lightspark.com + createdAt: '2026-04-08T15:35:00Z' + updatedAt: '2026-04-08T15:35:00Z' - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000003 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 type: PASSKEY + credentialId: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew nickname: iPhone Face-ID createdAt: '2026-04-09T10:15:00Z' updatedAt: '2026-04-09T10:15:00Z' @@ -15407,23 +15414,13 @@ components: format: date-time description: Timestamp after which this challenge is no longer valid. The signed retry must be submitted before this time. example: '2026-04-08T15:35:00Z' - AuthMethodType: - type: string - enum: - - OAUTH - - EMAIL_OTP - - PASSKEY - description: |- - The type of authentication credential. - - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. - - `EMAIL_OTP`: A one-time password delivered to the user's email address. - - `PASSKEY`: A WebAuthn passkey bound to the user's device. - AuthMethod: + AuthMethodBase: + title: Auth Method Base + description: Shared fields for authentication credential responses. type: object required: - id - accountId - - type - nickname - createdAt - updatedAt @@ -15436,8 +15433,6 @@ components: type: string description: Identifier of the internal account that this credential authenticates. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - type: - $ref: '#/components/schemas/AuthMethodType' nickname: type: string description: Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time. @@ -15452,6 +15447,66 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' + EmailOtpAuthMethod: + title: Email OTP Auth Method + description: Authentication credential response for an EMAIL_OTP auth method. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - EMAIL_OTP + description: Discriminator value identifying this as an email OTP credential. + OauthAuthMethod: + title: OAuth Auth Method + description: Authentication credential response for an OAUTH auth method. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth credential. + PasskeyAuthMethod: + title: Passkey Auth Method + description: Authentication credential response for a PASSKEY auth method. Extends the base auth method fields with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + - credentialId + properties: + type: + type: string + enum: + - PASSKEY + description: Discriminator value identifying this as a passkey credential. + credentialId: + type: string + description: Base64url-encoded WebAuthn credential identifier for this passkey. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew + AuthCredentialListItem: + title: Auth Credential List Item + description: Authentication credential returned from `GET /auth/credentials`. Passkey credentials include the WebAuthn `credentialId` needed to target a specific registered passkey; email OTP and OAuth credentials use the base list item shape. + oneOf: + - $ref: '#/components/schemas/EmailOtpAuthMethod' + - $ref: '#/components/schemas/OauthAuthMethod' + - $ref: '#/components/schemas/PasskeyAuthMethod' + discriminator: + propertyName: type + mapping: + EMAIL_OTP: '#/components/schemas/EmailOtpAuthMethod' + OAUTH: '#/components/schemas/OauthAuthMethod' + PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15461,7 +15516,18 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthMethod' + $ref: '#/components/schemas/AuthCredentialListItem' + AuthMethodType: + type: string + enum: + - OAUTH + - EMAIL_OTP + - PASSKEY + description: |- + The type of authentication credential. + - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. + - `EMAIL_OTP`: A one-time password delivered to the user's email address. + - `PASSKEY`: A WebAuthn passkey bound to the user's device. AuthCredentialCreateRequest: type: object required: @@ -15582,6 +15648,17 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' + AuthMethod: + title: Auth Method + description: Authentication credential response. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + $ref: '#/components/schemas/AuthMethodType' AuthMethodResponse: title: Auth Method Response description: 'Strict wrapper around `AuthMethod`. Used directly as the registration response on `POST /auth/credentials` (all three credential types) and inside `AuthCredentialResponseOneOf` for the `EMAIL_OTP` branch of `POST /auth/credentials/{id}/challenge`. The only difference from `AuthMethod` is `unevaluatedProperties: false`, which disambiguates the oneOf against `PasskeyAuthChallenge` — without the strictness, an `AuthMethod` with extra fields would ambiguously match both branches.' diff --git a/openapi.yaml b/openapi.yaml index dcadafc8..eaffc32e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3910,7 +3910,7 @@ paths: $ref: '#/components/schemas/AuthCredentialListResponse' examples: multipleCredentials: - summary: Internal account with an email OTP and a passkey credential + summary: Internal account with multiple authentication credentials value: data: - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 @@ -3919,9 +3919,16 @@ paths: nickname: example@lightspark.com createdAt: '2026-04-08T15:30:01Z' updatedAt: '2026-04-08T15:30:01Z' + - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000004 + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: OAUTH + nickname: example@lightspark.com + createdAt: '2026-04-08T15:35:00Z' + updatedAt: '2026-04-08T15:35:00Z' - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000003 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 type: PASSKEY + credentialId: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew nickname: iPhone Face-ID createdAt: '2026-04-09T10:15:00Z' updatedAt: '2026-04-09T10:15:00Z' @@ -15407,23 +15414,13 @@ components: format: date-time description: Timestamp after which this challenge is no longer valid. The signed retry must be submitted before this time. example: '2026-04-08T15:35:00Z' - AuthMethodType: - type: string - enum: - - OAUTH - - EMAIL_OTP - - PASSKEY - description: |- - The type of authentication credential. - - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. - - `EMAIL_OTP`: A one-time password delivered to the user's email address. - - `PASSKEY`: A WebAuthn passkey bound to the user's device. - AuthMethod: + AuthMethodBase: + title: Auth Method Base + description: Shared fields for authentication credential responses. type: object required: - id - accountId - - type - nickname - createdAt - updatedAt @@ -15436,8 +15433,6 @@ components: type: string description: Identifier of the internal account that this credential authenticates. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - type: - $ref: '#/components/schemas/AuthMethodType' nickname: type: string description: Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time. @@ -15452,6 +15447,66 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' + EmailOtpAuthMethod: + title: Email OTP Auth Method + description: Authentication credential response for an EMAIL_OTP auth method. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - EMAIL_OTP + description: Discriminator value identifying this as an email OTP credential. + OauthAuthMethod: + title: OAuth Auth Method + description: Authentication credential response for an OAUTH auth method. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth credential. + PasskeyAuthMethod: + title: Passkey Auth Method + description: Authentication credential response for a PASSKEY auth method. Extends the base auth method fields with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + - credentialId + properties: + type: + type: string + enum: + - PASSKEY + description: Discriminator value identifying this as a passkey credential. + credentialId: + type: string + description: Base64url-encoded WebAuthn credential identifier for this passkey. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew + AuthCredentialListItem: + title: Auth Credential List Item + description: Authentication credential returned from `GET /auth/credentials`. Passkey credentials include the WebAuthn `credentialId` needed to target a specific registered passkey; email OTP and OAuth credentials use the base list item shape. + oneOf: + - $ref: '#/components/schemas/EmailOtpAuthMethod' + - $ref: '#/components/schemas/OauthAuthMethod' + - $ref: '#/components/schemas/PasskeyAuthMethod' + discriminator: + propertyName: type + mapping: + EMAIL_OTP: '#/components/schemas/EmailOtpAuthMethod' + OAUTH: '#/components/schemas/OauthAuthMethod' + PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15461,7 +15516,18 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthMethod' + $ref: '#/components/schemas/AuthCredentialListItem' + AuthMethodType: + type: string + enum: + - OAUTH + - EMAIL_OTP + - PASSKEY + description: |- + The type of authentication credential. + - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. + - `EMAIL_OTP`: A one-time password delivered to the user's email address. + - `PASSKEY`: A WebAuthn passkey bound to the user's device. AuthCredentialCreateRequest: type: object required: @@ -15582,6 +15648,17 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' + AuthMethod: + title: Auth Method + description: Authentication credential response. + allOf: + - $ref: '#/components/schemas/AuthMethodBase' + - type: object + required: + - type + properties: + type: + $ref: '#/components/schemas/AuthMethodType' AuthMethodResponse: title: Auth Method Response description: 'Strict wrapper around `AuthMethod`. Used directly as the registration response on `POST /auth/credentials` (all three credential types) and inside `AuthCredentialResponseOneOf` for the `EMAIL_OTP` branch of `POST /auth/credentials/{id}/challenge`. The only difference from `AuthMethod` is `unevaluatedProperties: false`, which disambiguates the oneOf against `PasskeyAuthChallenge` — without the strictness, an `AuthMethod` with extra fields would ambiguously match both branches.' diff --git a/openapi/components/schemas/auth/AuthCredentialListItem.yaml b/openapi/components/schemas/auth/AuthCredentialListItem.yaml new file mode 100644 index 00000000..57f28dad --- /dev/null +++ b/openapi/components/schemas/auth/AuthCredentialListItem.yaml @@ -0,0 +1,16 @@ +title: Auth Credential List Item +description: >- + Authentication credential returned from `GET /auth/credentials`. Passkey + credentials include the WebAuthn `credentialId` needed to target a specific + registered passkey; email OTP and OAuth credentials use the base list item + shape. +oneOf: + - $ref: ./EmailOtpAuthMethod.yaml + - $ref: ./OauthAuthMethod.yaml + - $ref: ./PasskeyAuthMethod.yaml +discriminator: + propertyName: type + mapping: + EMAIL_OTP: ./EmailOtpAuthMethod.yaml + OAUTH: ./OauthAuthMethod.yaml + PASSKEY: ./PasskeyAuthMethod.yaml diff --git a/openapi/components/schemas/auth/AuthCredentialListResponse.yaml b/openapi/components/schemas/auth/AuthCredentialListResponse.yaml index 4dd0ecee..1eb42c75 100644 --- a/openapi/components/schemas/auth/AuthCredentialListResponse.yaml +++ b/openapi/components/schemas/auth/AuthCredentialListResponse.yaml @@ -6,4 +6,4 @@ properties: type: array description: List of authentication credentials registered on the internal account. items: - $ref: ./AuthMethod.yaml + $ref: ./AuthCredentialListItem.yaml diff --git a/openapi/components/schemas/auth/AuthMethod.yaml b/openapi/components/schemas/auth/AuthMethod.yaml index 1c955e8a..9570e4d9 100644 --- a/openapi/components/schemas/auth/AuthMethod.yaml +++ b/openapi/components/schemas/auth/AuthMethod.yaml @@ -1,37 +1,10 @@ -type: object -required: - - id - - accountId - - type - - nickname - - createdAt - - updatedAt -properties: - id: - type: string - description: System-generated unique identifier for the authentication credential. - example: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 - accountId: - type: string - description: Identifier of the internal account that this credential authenticates. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - type: - $ref: ./AuthMethodType.yaml - nickname: - type: string - description: >- - Human-readable identifier for this credential. For EMAIL_OTP credentials - this is the email address; for OAUTH credentials it is typically the email - claim from the OIDC token; for PASSKEY credentials it is the validated - nickname provided at registration time. - example: example@lightspark.com - createdAt: - type: string - format: date-time - description: Creation timestamp. - example: '2026-04-08T15:30:01Z' - updatedAt: - type: string - format: date-time - description: Last update timestamp. - example: '2026-04-08T15:35:00Z' +title: Auth Method +description: Authentication credential response. +allOf: + - $ref: ./AuthMethodBase.yaml + - type: object + required: + - type + properties: + type: + $ref: ./AuthMethodType.yaml diff --git a/openapi/components/schemas/auth/AuthMethodBase.yaml b/openapi/components/schemas/auth/AuthMethodBase.yaml new file mode 100644 index 00000000..0b6cab39 --- /dev/null +++ b/openapi/components/schemas/auth/AuthMethodBase.yaml @@ -0,0 +1,36 @@ +title: Auth Method Base +description: Shared fields for authentication credential responses. +type: object +required: + - id + - accountId + - nickname + - createdAt + - updatedAt +properties: + id: + type: string + description: System-generated unique identifier for the authentication credential. + example: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 + accountId: + type: string + description: Identifier of the internal account that this credential authenticates. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + nickname: + type: string + description: >- + Human-readable identifier for this credential. For EMAIL_OTP credentials + this is the email address; for OAUTH credentials it is typically the email + claim from the OIDC token; for PASSKEY credentials it is the validated + nickname provided at registration time. + example: example@lightspark.com + createdAt: + type: string + format: date-time + description: Creation timestamp. + example: '2026-04-08T15:30:01Z' + updatedAt: + type: string + format: date-time + description: Last update timestamp. + example: '2026-04-08T15:35:00Z' diff --git a/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml b/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml new file mode 100644 index 00000000..b9a930af --- /dev/null +++ b/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml @@ -0,0 +1,14 @@ +title: Email OTP Auth Method +description: Authentication credential response for an EMAIL_OTP auth method. +allOf: + - $ref: ./AuthMethodBase.yaml + - type: object + required: + - type + properties: + type: + type: string + enum: + - EMAIL_OTP + description: >- + Discriminator value identifying this as an email OTP credential. diff --git a/openapi/components/schemas/auth/OauthAuthMethod.yaml b/openapi/components/schemas/auth/OauthAuthMethod.yaml new file mode 100644 index 00000000..7c9c07eb --- /dev/null +++ b/openapi/components/schemas/auth/OauthAuthMethod.yaml @@ -0,0 +1,13 @@ +title: OAuth Auth Method +description: Authentication credential response for an OAUTH auth method. +allOf: + - $ref: ./AuthMethodBase.yaml + - type: object + required: + - type + properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth credential. diff --git a/openapi/components/schemas/auth/PasskeyAuthMethod.yaml b/openapi/components/schemas/auth/PasskeyAuthMethod.yaml new file mode 100644 index 00000000..f747981c --- /dev/null +++ b/openapi/components/schemas/auth/PasskeyAuthMethod.yaml @@ -0,0 +1,25 @@ +title: Passkey Auth Method +description: >- + Authentication credential response for a PASSKEY auth method. Extends the + base auth method fields with the WebAuthn credential identifier needed by + clients to target this passkey in `navigator.credentials.get()`. +allOf: + - $ref: ./AuthMethodBase.yaml + - type: object + required: + - type + - credentialId + properties: + type: + type: string + enum: + - PASSKEY + description: Discriminator value identifying this as a passkey credential. + credentialId: + type: string + description: >- + Base64url-encoded WebAuthn credential identifier for this passkey. + Corresponds to `PublicKeyCredential.rawId`; pass this value as + `allowCredentials[].id` when requesting a passkey assertion for this + auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew diff --git a/openapi/paths/auth/auth_credentials.yaml b/openapi/paths/auth/auth_credentials.yaml index 1e8c1117..f60cb266 100644 --- a/openapi/paths/auth/auth_credentials.yaml +++ b/openapi/paths/auth/auth_credentials.yaml @@ -228,7 +228,7 @@ get: $ref: ../../components/schemas/auth/AuthCredentialListResponse.yaml examples: multipleCredentials: - summary: Internal account with an email OTP and a passkey credential + summary: Internal account with multiple authentication credentials value: data: - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 @@ -237,9 +237,16 @@ get: nickname: example@lightspark.com createdAt: '2026-04-08T15:30:01Z' updatedAt: '2026-04-08T15:30:01Z' + - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000004 + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: OAUTH + nickname: example@lightspark.com + createdAt: '2026-04-08T15:35:00Z' + updatedAt: '2026-04-08T15:35:00Z' - id: AuthMethod:019542f5-b3e7-1d02-0000-000000000003 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 type: PASSKEY + credentialId: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew nickname: iPhone Face-ID createdAt: '2026-04-09T10:15:00Z' updatedAt: '2026-04-09T10:15:00Z' From c0c5dbaf52308b03ca4f22b3b9a56be7988d90bd Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Mon, 11 May 2026 13:53:22 -0700 Subject: [PATCH 2/2] Simplify auth credential list schema --- mintlify/openapi.yaml | 106 ++++-------------- openapi.yaml | 106 ++++-------------- .../schemas/auth/AuthCredentialListItem.yaml | 16 --- .../auth/AuthCredentialListResponse.yaml | 2 +- .../components/schemas/auth/AuthMethod.yaml | 55 +++++++-- .../schemas/auth/AuthMethodBase.yaml | 36 ------ .../schemas/auth/EmailOtpAuthMethod.yaml | 14 --- .../schemas/auth/OauthAuthMethod.yaml | 13 --- .../schemas/auth/PasskeyAuthMethod.yaml | 25 ----- 9 files changed, 86 insertions(+), 287 deletions(-) delete mode 100644 openapi/components/schemas/auth/AuthCredentialListItem.yaml delete mode 100644 openapi/components/schemas/auth/AuthMethodBase.yaml delete mode 100644 openapi/components/schemas/auth/EmailOtpAuthMethod.yaml delete mode 100644 openapi/components/schemas/auth/OauthAuthMethod.yaml delete mode 100644 openapi/components/schemas/auth/PasskeyAuthMethod.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index eaffc32e..e82a2265 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -15414,13 +15414,23 @@ components: format: date-time description: Timestamp after which this challenge is no longer valid. The signed retry must be submitted before this time. example: '2026-04-08T15:35:00Z' - AuthMethodBase: - title: Auth Method Base - description: Shared fields for authentication credential responses. + AuthMethodType: + type: string + enum: + - OAUTH + - EMAIL_OTP + - PASSKEY + description: |- + The type of authentication credential. + - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. + - `EMAIL_OTP`: A one-time password delivered to the user's email address. + - `PASSKEY`: A WebAuthn passkey bound to the user's device. + AuthMethod: type: object required: - id - accountId + - type - nickname - createdAt - updatedAt @@ -15433,6 +15443,12 @@ components: type: string description: Identifier of the internal account that this credential authenticates. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: + $ref: '#/components/schemas/AuthMethodType' + credentialId: + type: string + description: Base64url-encoded WebAuthn credential identifier for this passkey. Present only for `PASSKEY` authentication credentials. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew nickname: type: string description: Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time. @@ -15447,66 +15463,6 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' - EmailOtpAuthMethod: - title: Email OTP Auth Method - description: Authentication credential response for an EMAIL_OTP auth method. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - type: string - enum: - - EMAIL_OTP - description: Discriminator value identifying this as an email OTP credential. - OauthAuthMethod: - title: OAuth Auth Method - description: Authentication credential response for an OAUTH auth method. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - type: string - enum: - - OAUTH - description: Discriminator value identifying this as an OAuth credential. - PasskeyAuthMethod: - title: Passkey Auth Method - description: Authentication credential response for a PASSKEY auth method. Extends the base auth method fields with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - - credentialId - properties: - type: - type: string - enum: - - PASSKEY - description: Discriminator value identifying this as a passkey credential. - credentialId: - type: string - description: Base64url-encoded WebAuthn credential identifier for this passkey. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. - example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew - AuthCredentialListItem: - title: Auth Credential List Item - description: Authentication credential returned from `GET /auth/credentials`. Passkey credentials include the WebAuthn `credentialId` needed to target a specific registered passkey; email OTP and OAuth credentials use the base list item shape. - oneOf: - - $ref: '#/components/schemas/EmailOtpAuthMethod' - - $ref: '#/components/schemas/OauthAuthMethod' - - $ref: '#/components/schemas/PasskeyAuthMethod' - discriminator: - propertyName: type - mapping: - EMAIL_OTP: '#/components/schemas/EmailOtpAuthMethod' - OAUTH: '#/components/schemas/OauthAuthMethod' - PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15516,18 +15472,7 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthCredentialListItem' - AuthMethodType: - type: string - enum: - - OAUTH - - EMAIL_OTP - - PASSKEY - description: |- - The type of authentication credential. - - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. - - `EMAIL_OTP`: A one-time password delivered to the user's email address. - - `PASSKEY`: A WebAuthn passkey bound to the user's device. + $ref: '#/components/schemas/AuthMethod' AuthCredentialCreateRequest: type: object required: @@ -15648,17 +15593,6 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' - AuthMethod: - title: Auth Method - description: Authentication credential response. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - $ref: '#/components/schemas/AuthMethodType' AuthMethodResponse: title: Auth Method Response description: 'Strict wrapper around `AuthMethod`. Used directly as the registration response on `POST /auth/credentials` (all three credential types) and inside `AuthCredentialResponseOneOf` for the `EMAIL_OTP` branch of `POST /auth/credentials/{id}/challenge`. The only difference from `AuthMethod` is `unevaluatedProperties: false`, which disambiguates the oneOf against `PasskeyAuthChallenge` — without the strictness, an `AuthMethod` with extra fields would ambiguously match both branches.' diff --git a/openapi.yaml b/openapi.yaml index eaffc32e..e82a2265 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -15414,13 +15414,23 @@ components: format: date-time description: Timestamp after which this challenge is no longer valid. The signed retry must be submitted before this time. example: '2026-04-08T15:35:00Z' - AuthMethodBase: - title: Auth Method Base - description: Shared fields for authentication credential responses. + AuthMethodType: + type: string + enum: + - OAUTH + - EMAIL_OTP + - PASSKEY + description: |- + The type of authentication credential. + - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. + - `EMAIL_OTP`: A one-time password delivered to the user's email address. + - `PASSKEY`: A WebAuthn passkey bound to the user's device. + AuthMethod: type: object required: - id - accountId + - type - nickname - createdAt - updatedAt @@ -15433,6 +15443,12 @@ components: type: string description: Identifier of the internal account that this credential authenticates. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: + $ref: '#/components/schemas/AuthMethodType' + credentialId: + type: string + description: Base64url-encoded WebAuthn credential identifier for this passkey. Present only for `PASSKEY` authentication credentials. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew nickname: type: string description: Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time. @@ -15447,66 +15463,6 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' - EmailOtpAuthMethod: - title: Email OTP Auth Method - description: Authentication credential response for an EMAIL_OTP auth method. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - type: string - enum: - - EMAIL_OTP - description: Discriminator value identifying this as an email OTP credential. - OauthAuthMethod: - title: OAuth Auth Method - description: Authentication credential response for an OAUTH auth method. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - type: string - enum: - - OAUTH - description: Discriminator value identifying this as an OAuth credential. - PasskeyAuthMethod: - title: Passkey Auth Method - description: Authentication credential response for a PASSKEY auth method. Extends the base auth method fields with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - - credentialId - properties: - type: - type: string - enum: - - PASSKEY - description: Discriminator value identifying this as a passkey credential. - credentialId: - type: string - description: Base64url-encoded WebAuthn credential identifier for this passkey. Corresponds to `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` when requesting a passkey assertion for this auth method. - example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew - AuthCredentialListItem: - title: Auth Credential List Item - description: Authentication credential returned from `GET /auth/credentials`. Passkey credentials include the WebAuthn `credentialId` needed to target a specific registered passkey; email OTP and OAuth credentials use the base list item shape. - oneOf: - - $ref: '#/components/schemas/EmailOtpAuthMethod' - - $ref: '#/components/schemas/OauthAuthMethod' - - $ref: '#/components/schemas/PasskeyAuthMethod' - discriminator: - propertyName: type - mapping: - EMAIL_OTP: '#/components/schemas/EmailOtpAuthMethod' - OAUTH: '#/components/schemas/OauthAuthMethod' - PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15516,18 +15472,7 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthCredentialListItem' - AuthMethodType: - type: string - enum: - - OAUTH - - EMAIL_OTP - - PASSKEY - description: |- - The type of authentication credential. - - `OAUTH`: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple. - - `EMAIL_OTP`: A one-time password delivered to the user's email address. - - `PASSKEY`: A WebAuthn passkey bound to the user's device. + $ref: '#/components/schemas/AuthMethod' AuthCredentialCreateRequest: type: object required: @@ -15648,17 +15593,6 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' - AuthMethod: - title: Auth Method - description: Authentication credential response. - allOf: - - $ref: '#/components/schemas/AuthMethodBase' - - type: object - required: - - type - properties: - type: - $ref: '#/components/schemas/AuthMethodType' AuthMethodResponse: title: Auth Method Response description: 'Strict wrapper around `AuthMethod`. Used directly as the registration response on `POST /auth/credentials` (all three credential types) and inside `AuthCredentialResponseOneOf` for the `EMAIL_OTP` branch of `POST /auth/credentials/{id}/challenge`. The only difference from `AuthMethod` is `unevaluatedProperties: false`, which disambiguates the oneOf against `PasskeyAuthChallenge` — without the strictness, an `AuthMethod` with extra fields would ambiguously match both branches.' diff --git a/openapi/components/schemas/auth/AuthCredentialListItem.yaml b/openapi/components/schemas/auth/AuthCredentialListItem.yaml deleted file mode 100644 index 57f28dad..00000000 --- a/openapi/components/schemas/auth/AuthCredentialListItem.yaml +++ /dev/null @@ -1,16 +0,0 @@ -title: Auth Credential List Item -description: >- - Authentication credential returned from `GET /auth/credentials`. Passkey - credentials include the WebAuthn `credentialId` needed to target a specific - registered passkey; email OTP and OAuth credentials use the base list item - shape. -oneOf: - - $ref: ./EmailOtpAuthMethod.yaml - - $ref: ./OauthAuthMethod.yaml - - $ref: ./PasskeyAuthMethod.yaml -discriminator: - propertyName: type - mapping: - EMAIL_OTP: ./EmailOtpAuthMethod.yaml - OAUTH: ./OauthAuthMethod.yaml - PASSKEY: ./PasskeyAuthMethod.yaml diff --git a/openapi/components/schemas/auth/AuthCredentialListResponse.yaml b/openapi/components/schemas/auth/AuthCredentialListResponse.yaml index 1eb42c75..4dd0ecee 100644 --- a/openapi/components/schemas/auth/AuthCredentialListResponse.yaml +++ b/openapi/components/schemas/auth/AuthCredentialListResponse.yaml @@ -6,4 +6,4 @@ properties: type: array description: List of authentication credentials registered on the internal account. items: - $ref: ./AuthCredentialListItem.yaml + $ref: ./AuthMethod.yaml diff --git a/openapi/components/schemas/auth/AuthMethod.yaml b/openapi/components/schemas/auth/AuthMethod.yaml index 9570e4d9..8b73f0b6 100644 --- a/openapi/components/schemas/auth/AuthMethod.yaml +++ b/openapi/components/schemas/auth/AuthMethod.yaml @@ -1,10 +1,45 @@ -title: Auth Method -description: Authentication credential response. -allOf: - - $ref: ./AuthMethodBase.yaml - - type: object - required: - - type - properties: - type: - $ref: ./AuthMethodType.yaml +type: object +required: + - id + - accountId + - type + - nickname + - createdAt + - updatedAt +properties: + id: + type: string + description: System-generated unique identifier for the authentication credential. + example: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 + accountId: + type: string + description: Identifier of the internal account that this credential authenticates. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + type: + $ref: ./AuthMethodType.yaml + credentialId: + type: string + description: >- + Base64url-encoded WebAuthn credential identifier for this passkey. + Present only for `PASSKEY` authentication credentials. Corresponds to + `PublicKeyCredential.rawId`; pass this value as `allowCredentials[].id` + when requesting a passkey assertion for this auth method. + example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew + nickname: + type: string + description: >- + Human-readable identifier for this credential. For EMAIL_OTP credentials + this is the email address; for OAUTH credentials it is typically the email + claim from the OIDC token; for PASSKEY credentials it is the validated + nickname provided at registration time. + example: example@lightspark.com + createdAt: + type: string + format: date-time + description: Creation timestamp. + example: '2026-04-08T15:30:01Z' + updatedAt: + type: string + format: date-time + description: Last update timestamp. + example: '2026-04-08T15:35:00Z' diff --git a/openapi/components/schemas/auth/AuthMethodBase.yaml b/openapi/components/schemas/auth/AuthMethodBase.yaml deleted file mode 100644 index 0b6cab39..00000000 --- a/openapi/components/schemas/auth/AuthMethodBase.yaml +++ /dev/null @@ -1,36 +0,0 @@ -title: Auth Method Base -description: Shared fields for authentication credential responses. -type: object -required: - - id - - accountId - - nickname - - createdAt - - updatedAt -properties: - id: - type: string - description: System-generated unique identifier for the authentication credential. - example: AuthMethod:019542f5-b3e7-1d02-0000-000000000001 - accountId: - type: string - description: Identifier of the internal account that this credential authenticates. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - nickname: - type: string - description: >- - Human-readable identifier for this credential. For EMAIL_OTP credentials - this is the email address; for OAUTH credentials it is typically the email - claim from the OIDC token; for PASSKEY credentials it is the validated - nickname provided at registration time. - example: example@lightspark.com - createdAt: - type: string - format: date-time - description: Creation timestamp. - example: '2026-04-08T15:30:01Z' - updatedAt: - type: string - format: date-time - description: Last update timestamp. - example: '2026-04-08T15:35:00Z' diff --git a/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml b/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml deleted file mode 100644 index b9a930af..00000000 --- a/openapi/components/schemas/auth/EmailOtpAuthMethod.yaml +++ /dev/null @@ -1,14 +0,0 @@ -title: Email OTP Auth Method -description: Authentication credential response for an EMAIL_OTP auth method. -allOf: - - $ref: ./AuthMethodBase.yaml - - type: object - required: - - type - properties: - type: - type: string - enum: - - EMAIL_OTP - description: >- - Discriminator value identifying this as an email OTP credential. diff --git a/openapi/components/schemas/auth/OauthAuthMethod.yaml b/openapi/components/schemas/auth/OauthAuthMethod.yaml deleted file mode 100644 index 7c9c07eb..00000000 --- a/openapi/components/schemas/auth/OauthAuthMethod.yaml +++ /dev/null @@ -1,13 +0,0 @@ -title: OAuth Auth Method -description: Authentication credential response for an OAUTH auth method. -allOf: - - $ref: ./AuthMethodBase.yaml - - type: object - required: - - type - properties: - type: - type: string - enum: - - OAUTH - description: Discriminator value identifying this as an OAuth credential. diff --git a/openapi/components/schemas/auth/PasskeyAuthMethod.yaml b/openapi/components/schemas/auth/PasskeyAuthMethod.yaml deleted file mode 100644 index f747981c..00000000 --- a/openapi/components/schemas/auth/PasskeyAuthMethod.yaml +++ /dev/null @@ -1,25 +0,0 @@ -title: Passkey Auth Method -description: >- - Authentication credential response for a PASSKEY auth method. Extends the - base auth method fields with the WebAuthn credential identifier needed by - clients to target this passkey in `navigator.credentials.get()`. -allOf: - - $ref: ./AuthMethodBase.yaml - - type: object - required: - - type - - credentialId - properties: - type: - type: string - enum: - - PASSKEY - description: Discriminator value identifying this as a passkey credential. - credentialId: - type: string - description: >- - Base64url-encoded WebAuthn credential identifier for this passkey. - Corresponds to `PublicKeyCredential.rawId`; pass this value as - `allowCredentials[].id` when requesting a passkey assertion for this - auth method. - example: KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew