diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index dcadafc8..b974a585 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' @@ -15452,6 +15459,42 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' + 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.' + allOf: + - $ref: '#/components/schemas/AuthMethod' + unevaluatedProperties: false + PasskeyAuthMethod: + title: Passkey Auth Method + description: Authentication credential response for a PASSKEY auth method. Extends the base `AuthMethod` shape with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. + allOf: + - $ref: '#/components/schemas/AuthMethod' + - type: object + required: + - 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; other credential types use the base `AuthMethod` shape. + oneOf: + - $ref: '#/components/schemas/AuthMethodResponse' + - $ref: '#/components/schemas/PasskeyAuthMethod' + discriminator: + propertyName: type + mapping: + EMAIL_OTP: '#/components/schemas/AuthMethodResponse' + OAUTH: '#/components/schemas/AuthMethodResponse' + PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15461,7 +15504,7 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthMethod' + $ref: '#/components/schemas/AuthCredentialListItem' AuthCredentialCreateRequest: type: object required: @@ -15582,12 +15625,6 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' - 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.' - allOf: - - $ref: '#/components/schemas/AuthMethod' - unevaluatedProperties: false AuthSignedRequestChallenge: title: Authentication Signed Request Challenge description: 202 response returned from Embedded Wallet Auth endpoints that require a signed retry — `POST /auth/credentials` (adding an additional credential), `DELETE /auth/credentials/{id}` (revoking a credential), and `DELETE /auth/sessions/{id}` (revoking a session). Carries the signing fields from `SignedRequestChallenge` plus the `type` of the authentication credential involved (being added, being revoked, or that issued the session being revoked). The client already knows the target resource id from the request path / body it just sent, so nothing beyond `type` is echoed in the response. diff --git a/openapi.yaml b/openapi.yaml index dcadafc8..b974a585 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' @@ -15452,6 +15459,42 @@ components: format: date-time description: Last update timestamp. example: '2026-04-08T15:35:00Z' + 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.' + allOf: + - $ref: '#/components/schemas/AuthMethod' + unevaluatedProperties: false + PasskeyAuthMethod: + title: Passkey Auth Method + description: Authentication credential response for a PASSKEY auth method. Extends the base `AuthMethod` shape with the WebAuthn credential identifier needed by clients to target this passkey in `navigator.credentials.get()`. + allOf: + - $ref: '#/components/schemas/AuthMethod' + - type: object + required: + - 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; other credential types use the base `AuthMethod` shape. + oneOf: + - $ref: '#/components/schemas/AuthMethodResponse' + - $ref: '#/components/schemas/PasskeyAuthMethod' + discriminator: + propertyName: type + mapping: + EMAIL_OTP: '#/components/schemas/AuthMethodResponse' + OAUTH: '#/components/schemas/AuthMethodResponse' + PASSKEY: '#/components/schemas/PasskeyAuthMethod' AuthCredentialListResponse: type: object required: @@ -15461,7 +15504,7 @@ components: type: array description: List of authentication credentials registered on the internal account. items: - $ref: '#/components/schemas/AuthMethod' + $ref: '#/components/schemas/AuthCredentialListItem' AuthCredentialCreateRequest: type: object required: @@ -15582,12 +15625,6 @@ components: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialCreateRequest' OAUTH: '#/components/schemas/OauthCredentialCreateRequest' PASSKEY: '#/components/schemas/PasskeyCredentialCreateRequest' - 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.' - allOf: - - $ref: '#/components/schemas/AuthMethod' - unevaluatedProperties: false AuthSignedRequestChallenge: title: Authentication Signed Request Challenge description: 202 response returned from Embedded Wallet Auth endpoints that require a signed retry — `POST /auth/credentials` (adding an additional credential), `DELETE /auth/credentials/{id}` (revoking a credential), and `DELETE /auth/sessions/{id}` (revoking a session). Carries the signing fields from `SignedRequestChallenge` plus the `type` of the authentication credential involved (being added, being revoked, or that issued the session being revoked). The client already knows the target resource id from the request path / body it just sent, so nothing beyond `type` is echoed in the response. diff --git a/openapi/components/schemas/auth/AuthCredentialListItem.yaml b/openapi/components/schemas/auth/AuthCredentialListItem.yaml new file mode 100644 index 00000000..9e9ce83d --- /dev/null +++ b/openapi/components/schemas/auth/AuthCredentialListItem.yaml @@ -0,0 +1,14 @@ +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; other credential types use the base `AuthMethod` shape. +oneOf: + - $ref: ./AuthMethodResponse.yaml + - $ref: ./PasskeyAuthMethod.yaml +discriminator: + propertyName: type + mapping: + EMAIL_OTP: ./AuthMethodResponse.yaml + OAUTH: ./AuthMethodResponse.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/PasskeyAuthMethod.yaml b/openapi/components/schemas/auth/PasskeyAuthMethod.yaml new file mode 100644 index 00000000..6f8f01f6 --- /dev/null +++ b/openapi/components/schemas/auth/PasskeyAuthMethod.yaml @@ -0,0 +1,24 @@ +title: Passkey Auth Method +description: >- + Authentication credential response for a PASSKEY auth method. Extends the + base `AuthMethod` shape with the WebAuthn credential identifier needed by + clients to target this passkey in `navigator.credentials.get()`. +allOf: + - $ref: ./AuthMethod.yaml + - type: object + required: + - 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'