diff --git a/.stainless/stainless.yml b/.stainless/stainless.yml index 351225cc..6976f945 100644 --- a/.stainless/stainless.yml +++ b/.stainless/stainless.yml @@ -346,6 +346,8 @@ resources: email_otp_credential_additional_challenge_fields: '#/components/schemas/EmailOtpCredentialAdditionalChallengeFields' oauth_credential_create_request: '#/components/schemas/OauthCredentialCreateRequest' oauth_credential_create_request_fields: '#/components/schemas/OauthCredentialCreateRequestFields' + oauth_credential_verify_request: '#/components/schemas/OauthCredentialVerifyRequest' + oauth_credential_verify_request_fields: '#/components/schemas/OauthCredentialVerifyRequestFields' exchange_rates: methods: list: @@ -857,6 +859,7 @@ openapi: args: target: - "$.components.schemas.EmailOtpCredentialVerifyRequest.allOf[0]" + - "$.components.schemas.OauthCredentialVerifyRequest.allOf[0]" keys: [ "$ref" ] codeflow: diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index bfe6f346..f84a6708 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -3712,7 +3712,9 @@ paths: description: | Complete the verification step for a previously created authentication credential and issue a session signing key. - For `EMAIL_OTP` credentials, supply the one-time password that was emailed to the user along with a client-generated public key. On success, the response contains an `encryptedSessionSigningKey` that is encrypted to the supplied `clientPublicKey`, along with an `expiresAt` timestamp marking when the session expires. The `clientPublicKey` is ephemeral and one-time-use per verification request. + For `EMAIL_OTP` credentials, supply the one-time password that was emailed to the user along with a client-generated public key. For `OAUTH` credentials, supply a fresh OIDC token (`iat` must be less than 60 seconds before the request) along with the client-generated public key; this is also the reauthentication path after a prior session expired. + + On success, the response contains an `encryptedSessionSigningKey` that is encrypted to the supplied `clientPublicKey`, along with an `expiresAt` timestamp marking when the session expires. The `clientPublicKey` is ephemeral and one-time-use per verification request. operationId: verifyAuthCredential tags: - Embedded Wallet Auth @@ -3738,6 +3740,12 @@ paths: type: EMAIL_OTP otp: '123456' clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 + oauth: + summary: Verify an OAuth credential + value: + type: OAUTH + oidcToken: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 responses: '200': description: Authentication credential verified and session issued @@ -3752,7 +3760,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized - invalid or expired OTP + description: Unauthorized. Returned for an invalid or expired OTP (`EMAIL_OTP`) or for an OIDC token whose signature, issuer, or `iat` freshness check failed (`OAUTH`). content: application/json: schema: @@ -13252,13 +13260,40 @@ components: allOf: - $ref: '#/components/schemas/AuthCredentialVerifyRequest' - $ref: '#/components/schemas/EmailOtpCredentialVerifyRequestFields' + OauthCredentialVerifyRequestFields: + type: object + required: + - type + - oidcToken + - clientPublicKey + properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth verification. + oidcToken: + type: string + description: OIDC ID token issued by the identity provider. For reauthentication after a prior session expired, supply a fresh token — the token's `iat` claim must be less than 60 seconds before the request timestamp. Grid fetches the issuer's signing key from the `iss` claim's `.well-known` OpenID configuration and verifies the token signature. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: + type: string + description: Client-generated P-256 public key, hex-encoded in uncompressed SEC1 format (0x04 prefix followed by the 32-byte X and 32-byte Y coordinates; 130 hex characters total). The matching private key must remain on the client. Grid encrypts the session signing key returned in the response to this public key. The key is ephemeral and one-time-use per verification request. + example: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 + OauthCredentialVerifyRequest: + title: OAuth Credential Verify Request + allOf: + - $ref: '#/components/schemas/AuthCredentialVerifyRequest' + - $ref: '#/components/schemas/OauthCredentialVerifyRequestFields' AuthCredentialVerifyRequestOneOf: oneOf: - $ref: '#/components/schemas/EmailOtpCredentialVerifyRequest' + - $ref: '#/components/schemas/OauthCredentialVerifyRequest' discriminator: propertyName: type mapping: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialVerifyRequest' + OAUTH: '#/components/schemas/OauthCredentialVerifyRequest' AuthSession: allOf: - $ref: '#/components/schemas/AuthMethod' diff --git a/openapi.yaml b/openapi.yaml index bfe6f346..f84a6708 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3712,7 +3712,9 @@ paths: description: | Complete the verification step for a previously created authentication credential and issue a session signing key. - For `EMAIL_OTP` credentials, supply the one-time password that was emailed to the user along with a client-generated public key. On success, the response contains an `encryptedSessionSigningKey` that is encrypted to the supplied `clientPublicKey`, along with an `expiresAt` timestamp marking when the session expires. The `clientPublicKey` is ephemeral and one-time-use per verification request. + For `EMAIL_OTP` credentials, supply the one-time password that was emailed to the user along with a client-generated public key. For `OAUTH` credentials, supply a fresh OIDC token (`iat` must be less than 60 seconds before the request) along with the client-generated public key; this is also the reauthentication path after a prior session expired. + + On success, the response contains an `encryptedSessionSigningKey` that is encrypted to the supplied `clientPublicKey`, along with an `expiresAt` timestamp marking when the session expires. The `clientPublicKey` is ephemeral and one-time-use per verification request. operationId: verifyAuthCredential tags: - Embedded Wallet Auth @@ -3738,6 +3740,12 @@ paths: type: EMAIL_OTP otp: '123456' clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 + oauth: + summary: Verify an OAuth credential + value: + type: OAUTH + oidcToken: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 responses: '200': description: Authentication credential verified and session issued @@ -3752,7 +3760,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized - invalid or expired OTP + description: Unauthorized. Returned for an invalid or expired OTP (`EMAIL_OTP`) or for an OIDC token whose signature, issuer, or `iat` freshness check failed (`OAUTH`). content: application/json: schema: @@ -13252,13 +13260,40 @@ components: allOf: - $ref: '#/components/schemas/AuthCredentialVerifyRequest' - $ref: '#/components/schemas/EmailOtpCredentialVerifyRequestFields' + OauthCredentialVerifyRequestFields: + type: object + required: + - type + - oidcToken + - clientPublicKey + properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth verification. + oidcToken: + type: string + description: OIDC ID token issued by the identity provider. For reauthentication after a prior session expired, supply a fresh token — the token's `iat` claim must be less than 60 seconds before the request timestamp. Grid fetches the issuer's signing key from the `iss` claim's `.well-known` OpenID configuration and verifies the token signature. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: + type: string + description: Client-generated P-256 public key, hex-encoded in uncompressed SEC1 format (0x04 prefix followed by the 32-byte X and 32-byte Y coordinates; 130 hex characters total). The matching private key must remain on the client. Grid encrypts the session signing key returned in the response to this public key. The key is ephemeral and one-time-use per verification request. + example: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 + OauthCredentialVerifyRequest: + title: OAuth Credential Verify Request + allOf: + - $ref: '#/components/schemas/AuthCredentialVerifyRequest' + - $ref: '#/components/schemas/OauthCredentialVerifyRequestFields' AuthCredentialVerifyRequestOneOf: oneOf: - $ref: '#/components/schemas/EmailOtpCredentialVerifyRequest' + - $ref: '#/components/schemas/OauthCredentialVerifyRequest' discriminator: propertyName: type mapping: EMAIL_OTP: '#/components/schemas/EmailOtpCredentialVerifyRequest' + OAUTH: '#/components/schemas/OauthCredentialVerifyRequest' AuthSession: allOf: - $ref: '#/components/schemas/AuthMethod' diff --git a/openapi/components/schemas/auth/AuthCredentialVerifyRequestOneOf.yaml b/openapi/components/schemas/auth/AuthCredentialVerifyRequestOneOf.yaml index 03eee7dd..8d26c0ab 100644 --- a/openapi/components/schemas/auth/AuthCredentialVerifyRequestOneOf.yaml +++ b/openapi/components/schemas/auth/AuthCredentialVerifyRequestOneOf.yaml @@ -1,6 +1,8 @@ oneOf: - $ref: ./EmailOtpCredentialVerifyRequest.yaml + - $ref: ./OauthCredentialVerifyRequest.yaml discriminator: propertyName: type mapping: EMAIL_OTP: ./EmailOtpCredentialVerifyRequest.yaml + OAUTH: ./OauthCredentialVerifyRequest.yaml diff --git a/openapi/components/schemas/auth/OauthCredentialVerifyRequest.yaml b/openapi/components/schemas/auth/OauthCredentialVerifyRequest.yaml new file mode 100644 index 00000000..0d6232cc --- /dev/null +++ b/openapi/components/schemas/auth/OauthCredentialVerifyRequest.yaml @@ -0,0 +1,4 @@ +title: OAuth Credential Verify Request +allOf: + - $ref: ./AuthCredentialVerifyRequest.yaml + - $ref: ./OauthCredentialVerifyRequestFields.yaml diff --git a/openapi/components/schemas/auth/OauthCredentialVerifyRequestFields.yaml b/openapi/components/schemas/auth/OauthCredentialVerifyRequestFields.yaml new file mode 100644 index 00000000..688b7338 --- /dev/null +++ b/openapi/components/schemas/auth/OauthCredentialVerifyRequestFields.yaml @@ -0,0 +1,31 @@ +type: object +required: + - type + - oidcToken + - clientPublicKey +properties: + type: + type: string + enum: + - OAUTH + description: Discriminator value identifying this as an OAuth verification. + oidcToken: + type: string + description: >- + OIDC ID token issued by the identity provider. For reauthentication + after a prior session expired, supply a fresh token — the token's + `iat` claim must be less than 60 seconds before the request + timestamp. Grid fetches the issuer's signing key from the `iss` + claim's `.well-known` OpenID configuration and verifies the token + signature. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: + type: string + description: >- + Client-generated P-256 public key, hex-encoded in uncompressed SEC1 + format (0x04 prefix followed by the 32-byte X and 32-byte Y + coordinates; 130 hex characters total). The matching private key + must remain on the client. Grid encrypts the session signing key + returned in the response to this public key. The key is ephemeral + and one-time-use per verification request. + example: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 diff --git a/openapi/paths/auth/auth_credentials_{id}_verify.yaml b/openapi/paths/auth/auth_credentials_{id}_verify.yaml index f361e7df..c847f356 100644 --- a/openapi/paths/auth/auth_credentials_{id}_verify.yaml +++ b/openapi/paths/auth/auth_credentials_{id}_verify.yaml @@ -6,11 +6,18 @@ post: For `EMAIL_OTP` credentials, supply the one-time password that was - emailed to the user along with a client-generated public key. On - success, the response contains an `encryptedSessionSigningKey` that is - encrypted to the supplied `clientPublicKey`, along with an `expiresAt` - timestamp marking when the session expires. The `clientPublicKey` is - ephemeral and one-time-use per verification request. + emailed to the user along with a client-generated public key. For + `OAUTH` credentials, supply a fresh OIDC token (`iat` must be less + than 60 seconds before the request) along with the client-generated + public key; this is also the reauthentication path after a prior + session expired. + + + On success, the response contains an `encryptedSessionSigningKey` + that is encrypted to the supplied `clientPublicKey`, along with an + `expiresAt` timestamp marking when the session expires. The + `clientPublicKey` is ephemeral and one-time-use per verification + request. operationId: verifyAuthCredential tags: - Embedded Wallet Auth @@ -38,6 +45,12 @@ post: type: EMAIL_OTP otp: '123456' clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 + oauth: + summary: Verify an OAuth credential + value: + type: OAUTH + oidcToken: eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMTIyMzM0NDU1IiwiYXVkIjoiMTIzNDU2Ny5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImlhdCI6MTc0NjczNjUwOSwiZXhwIjoxNzQ2NzQwMTA5fQ.signature + clientPublicKey: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2 responses: '200': description: Authentication credential verified and session issued @@ -52,7 +65,10 @@ post: schema: $ref: ../../components/schemas/errors/Error400.yaml '401': - description: Unauthorized - invalid or expired OTP + description: >- + Unauthorized. Returned for an invalid or expired OTP (`EMAIL_OTP`) + or for an OIDC token whose signature, issuer, or `iat` freshness + check failed (`OAUTH`). content: application/json: schema: