Updated API from documentation release

Author: ct-sdks[bot]

api-specs/api/examples/Customer/CustomerToken.json

@@ -12,5 +12,6 @@
   },
   "customerId": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
   "expiresAt": "2022-09-19T15:58:41.772Z",
-  "value": "Is5gdF7Ym-Aick-AkmsEHMMBWpByIfjgyXxKxZem"
+  "value": "Is5gdF7Ym-Aick-AkmsEHMMBWpByIfjgyXxKxZem",
+  "invalidateOlderTokens": true
 }

api-specs/api/resources/customers.raml

@@ -58,6 +58,10 @@ post:
         body:
           application/json:
             example: !include ../examples/customer.example.json
+      400:
+        description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+      404:
+        description: The provided token is invalid or does not exist.
 /email-token={emailToken}:
   (methodName): withEmailToken
   type:
@@ -74,6 +78,10 @@ post:
         body:
           application/json:
             example: !include ../examples/customer.example.json
+      400:
+        description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailTokenError) error is returned as the provided token has expired.
+      404:
+        description: The provided token is invalid or does not exist.
 /email-token:
   type: base
   post:
@@ -83,6 +91,7 @@ post:
       Use this method to create an email token for a global Customer during their [email verification process](/../api/customers-overview#customer-email-verification).
 
       Creating an email token for the Customer produces the [CustomerEmailTokenCreated](ctp:api:type:CustomerEmailTokenCreatedMessage) Message.
+      The Message will include the token's value, if the token's validity is 60 minutes or less.
     body:
       application/json:
         example: !include ../examples/Customer/CustomerCreateEmailToken.json
@@ -100,6 +109,8 @@ post:
       Use this method to verify a global Customer's email during their [email verification process](/../api/customers-overview#customer-email-verification).
 
       Verifying the email of the Customer produces the [CustomerEmailVerified](ctp:api:type:CustomerEmailVerifiedMessage) Message.
+
+      After the email is verified, all email tokens issued previously through the [email verification flow](/../api/projects/customers#email-verification-of-customer) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
     securedBy: [oauth_2_0: { scopes: ['manage_customers:{projectKey}'] }]
     body:
       application/json:
@@ -112,6 +123,10 @@ post:
           application/json:
             example: !include ../examples/customer.example.json
             type: Customer
+      400:
+        description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailToken) error is returned as the provided token is has expired.
+      404:
+        description: The provided token is invalid or does not exist.
 /password:
   type: base
   post:
@@ -136,9 +151,9 @@ post:
     description: |
       Use this method to reset a global Customer's password during their [password reset process](/../api/customers-overview#customer-password-reset).
 
-      After the password is reset, any previously issued access and/or refresh tokens created through the [password flow](/authorization#password-flow) or [refresh token flow](/authorization#refresh-token-flow) are invalidated.
-
       Resetting the password of the Customer produces the [CustomerPasswordUpdated](ctp:api:type:CustomerPasswordUpdatedMessage) Message with `reset=true`.
+
+      After the password is reset, all password tokens issued previously through the [password reset flow](/../api/projects/customers#password-reset-of-customer) are invalidated. In addition, any access and refresh tokens issued previously through the [password flow](/../api/authorization#password-flow) and [refresh token flow](/../api/authorization#refresh-token-flow) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
     securedBy: [oauth_2_0: { scopes: ['manage_customers:{projectKey}'] }]
     body:
       application/json:
@@ -150,6 +165,10 @@ post:
           application/json:
             example: !include ../examples/customer.example.json
             type: Customer
+      400:
+        description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+      404:
+        description: The provided token is invalid or does not exist.
 /password-token:
   type: base
   description: Produces the [CustomerPasswordTokenCreated](ctp:api:type:CustomerPasswordTokenCreatedMessage) Message.
@@ -159,7 +178,8 @@ post:
     description: |
       Use this method to create a password reset token for a global Customer during their [password reset process](/../api/customers-overview#customer-password-reset).
 
-      Creating a password reset token does not invalidate existing tokens.
+      Creating a password reset token for the Customer produces the [CustomerPasswordTokenCreated](ctp:api:type:CustomerPasswordTokenCreatedMessage) Message.
+      The Message will include the token's value, if the token's validity is 60 minutes or less.
     body:
       application/json:
         example: !include ../examples/Customer/CustomerCreatePasswordResetToken.json

api-specs/api/resources/in-store.raml

@@ -1600,11 +1600,12 @@ uriParameters:
       description: |
         This is the last step in the [email verification process of a Customer](/../api/projects/customers#email-verification-of-customer-in-store). Returns a `200 OK` status if successful.
 
+        After the email is verified, all email tokens issued previously through the [email verification flow](/../api/projects/customers#email-verification-of-customer) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
+
         A [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error is returned in the following scenarios:
 
         - If no Customer exists with the `id` specified in the [customer:{id}](/scopes#composable-commerce-oauth) scope.
         - If the Customer exists but is associated with a different Store than what is specified in the `manage_my_profile:{projectKey}:{storeKey}` scope.
-
       securedBy:
         [
           oauth_2_0:
@@ -1628,6 +1629,10 @@ uriParameters:
             application/json:
               example: !include ../examples/customer.example.json
               type: Customer
+        400:
+          description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailToken) error is returned as the provided token is has expired.
+        404:
+          description: The provided token is invalid or does not exist.
   /password:
     type: base
     post:
@@ -1673,11 +1678,12 @@ uriParameters:
 
           Resetting a password produces the Customer [CustomerPasswordUpdated](ctp:api:type:CustomerPasswordUpdatedMessage) Message with `reset=true`.
 
+          After the password is reset, all password tokens issued previously through the [password reset flow](/../api/projects/customers#password-reset-of-customer) are invalidated. In addition, any access and refresh tokens issued previously through the [password flow](/../api/authorization#password-flow) and [refresh token flow](/../api/authorization#refresh-token-flow) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
+
           A [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error is returned in the following scenarios:
 
           - If no Customer exists with the `id` specified in the [customer:{id}](/scopes#composable-commerce-oauth) scope.
           - If the Customer exists but is associated with a different Store than what is specified in the `manage_my_profile:{projectKey}:{storeKey}` scope.
-
         securedBy:
           [
             oauth_2_0:
@@ -1700,6 +1706,10 @@ uriParameters:
               application/json:
                 example: !include ../examples/customer.example.json
                 type: Customer
+          400:
+            description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+          404:
+            description: The provided token is invalid or does not exist.
   /signup:
     type: base
     post:
@@ -1857,6 +1867,10 @@ uriParameters:
           body:
             application/json:
               example: !include ../examples/customer.example.json
+        400:
+          description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+        404:
+          description: The provided token is invalid or does not exist.
   /email-token={emailToken}:
     (methodName): withEmailToken
     type:
@@ -1879,6 +1893,10 @@ uriParameters:
           body:
             application/json:
               example: !include ../examples/customer.example.json
+        400:
+          description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailTokenError) error is returned as the provided token has expired.
+        404:
+          description: The provided token is invalid or does not exist.
   /email-token:
     type: base
     post:
@@ -1887,6 +1905,9 @@ uriParameters:
         Use this method to create an email token for a Store-specific Customer during their [email verification process](/../api/customers-overview#customer-email-verification).
 
         If the Customer exists in the Project but the `stores` field references a different Store, this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
+
+        Creating an email token for the Customer produces the [CustomerEmailTokenCreated](ctp:api:type:CustomerEmailTokenCreatedMessage) Message.
+        The Message will include the token's value, if the token's validity is 60 minutes or less.
       securedBy:
         - oauth_2_0:
             scopes:
@@ -1911,6 +1932,8 @@ uriParameters:
         Verifying the email of the Customer produces the [CustomerEmailVerified](ctp:api:type:CustomerEmailVerifiedMessage) Message.
 
         If the Customer exists in the Project but the `stores` field references a different [Store](ctp:api:type:Store), this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
+
+        After the email is verified, all email tokens issued previously through the [email verification flow](/../api/projects/customers#email-verification-of-customer) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
       securedBy:
         - oauth_2_0:
             scopes:
@@ -1927,6 +1950,10 @@ uriParameters:
             application/json:
               example: !include ../examples/customer.example.json
               type: Customer
+        400:
+          description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailTokenError) error is returned as the provided token has expired.
+        404:
+          description: The provided token is invalid or does not exist.
   /password:
     type: base
     post:
@@ -1955,12 +1982,11 @@ uriParameters:
       description: |
         Use this method to reset a Store-specific Customer's password during their [password reset process](/../api/customers-overview#customer-password-reset).
 
-        After the password is reset, any previously issued access and/or refresh tokens created through the [password flow](/authorization#password-flow) or [refresh token flow](/authorization#refresh-token-flow) are invalidated.
-
         Resetting the password of the Customer produces the [CustomerPasswordUpdated](ctp:api:type:CustomerPasswordUpdatedMessage) Message with `reset=true`.
 
-        If the Customer exists in the Project but the `stores` field references a different [Store](ctp:api:type:Store), then this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
+        After the password is reset, all password tokens issued previously through the [password reset flow](/../api/projects/customers#password-reset-of-customer) are invalidated. In addition, any access and refresh tokens issued previously through the [password flow](/../api/authorization#password-flow) and [refresh token flow](/../api/authorization#refresh-token-flow) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
 
+        If the Customer exists in the Project but the `stores` field references a different [Store](ctp:api:type:Store), then this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
       securedBy:
         - oauth_2_0:
             scopes:
@@ -1976,16 +2002,21 @@ uriParameters:
             application/json:
               example: !include ../examples/customer.example.json
               type: Customer
+        400:
+          description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+        404:
+          description: The provided token is invalid or does not exist.
   /password-token:
     type: base
     post:
       displayName: Create password reset token for Customer in Store
       description: |
         Use this method to create a password reset token for a Store-specific Customer during their [password reset process](/../api/customers-overview#customer-password-reset).
 
-        Creating a password reset token does not invalidate existing tokens.
-
         If the Customer exists in the Project but the `stores` field references a different Store, this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
+
+        Creating a password reset token for the Customer produces the [CustomerPasswordTokenCreated](ctp:api:type:CustomerPasswordTokenCreatedMessage) Message.
+        The Message will include the token's value, if the token's validity is 60 minutes or less.
       securedBy:
         - oauth_2_0:
             scopes:

api-specs/api/resources/me.raml

@@ -68,6 +68,8 @@ delete:
     displayName: Verify email of My Customer
     description: |
       This is the last step in the [email verification process of a Customer](/../api/projects/customers#email-verification-of-customer).
+
+      After the email is verified, all email tokens issued previously through the [email verification flow](/../api/projects/customers#email-verification-of-customer) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
     securedBy:
       [
         oauth_2_0:
@@ -84,6 +86,10 @@ delete:
           application/json:
             example: !include ../examples/customer.example.json
             type: Customer
+      400:
+        description: An [ExpiredCustomerEmailToken](ctp:api:type:ExpiredCustomerEmailToken) error is returned as the provided token is has expired.
+      404:
+        description: The provided token is invalid or does not exist.
 /password:
   type: base
   post:
@@ -117,6 +123,8 @@ delete:
         This is the last step in the [password reset process of a Customer](/../api/projects/customers#password-reset-of-customer).
 
         Resetting a password of the Customer produces the [CustomerPasswordUpdated](ctp:api:type:CustomerPasswordUpdatedMessage) Message with `reset=true`.
+
+        After the password is reset, all password tokens issued previously through the [password reset flow](/../api/projects/customers#password-reset-of-customer) are invalidated. In addition, any access and refresh tokens issued previously through the [password flow](/../api/authorization#password-flow) and [refresh token flow](/../api/authorization#refresh-token-flow) are invalidated. This invalidation of tokens is [eventually consistent](/../api/general-concepts#eventual-consistency).
       securedBy:
         [
           oauth_2_0:
@@ -132,6 +140,10 @@ delete:
             application/json:
               example: !include ../examples/customer.example.json
               type: Customer
+        400:
+          description: An [ExpiredCustomerPasswordToken](ctp:api:type:ExpiredCustomerPasswordTokenError) error is returned as the provided token has expired.
+        404:
+          description: The provided token is invalid or does not exist.
 /signup:
   type: base
   post:

api-specs/api/types/customer/CustomerCreateEmailToken.raml

@@ -15,3 +15,8 @@ properties:
     type: number
     format: int64
     description: Validity period of the generated token in minutes.
+  invalidateOlderTokens?:
+    type: boolean
+    default: false
+    description: |
+      If set to `true`, all email tokens issued previously for the Customer will be invalidated.

api-specs/api/types/customer/CustomerCreatePasswordResetToken.raml

@@ -13,4 +13,9 @@ properties:
     format: int64
     description: |
       Validity period of the generated token in minutes.
-    default: 34560
+    default: 1440
+  invalidateOlderTokens?:
+    type: boolean
+    default: false
+    description: |
+      If set to `true`, all password tokens issued previously for the Customer will be invalidated.

api-specs/api/types/customer/CustomerToken.raml

@@ -20,6 +20,10 @@ properties:
     type: datetime
     description: |
       Date and time (UTC) the token expires.
+  invalidateOlderTokens:
+    type: boolean
+    description: |
+      If `true`, all tokens issued previously for the Customer will be invalidated.
   createdAt:
     type: datetime
     description: |

api-specs/api/types/error/ExpiredCustomerEmailTokenError.raml

@@ -0,0 +1,19 @@
+#%RAML 1.0 DataType
+(package): Error
+type: ErrorObject
+displayName: ExpiredCustomerEmailTokenError
+discriminatorValue: ExpiredCustomerEmailToken
+description: |
+  Returned when the provided email token of the Customer has expired.
+
+  The error is returned as a failed response to:
+
+  - [Get Customer by email token](ctp:api:endpoint:/{projectKey}/customers/email-token={emailToken}:GET) and [Get Customer in Store by email token](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/email-token={emailToken}:GET) requests
+  - [Verify email of Customer](ctp:api:endpoint:/{projectKey}/customers/email/confirm:POST) and [Verify email of Customer in Store](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/email/confirm:POST) requests
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      `"The given email token has expired."`

api-specs/api/types/error/ExpiredCustomerPasswordTokenError.raml

@@ -0,0 +1,19 @@
+#%RAML 1.0 DataType
+(package): Error
+type: ErrorObject
+displayName: ExpiredCustomerPasswordTokenError
+discriminatorValue: ExpiredCustomerPasswordToken
+description: |
+  Returned when the provided password token of the Customer has expired.
+
+  The error is returned as a failed response to:
+
+  - [Get Customer by password token](ctp:api:endpoint:/{projectKey}/customers/password-token={passwordToken}:GET) and [Get Customer in Store by password token](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/password-token={passwordToken}:GET) requests
+  - [Reset password of Customer](ctp:api:endpoint:/{projectKey}/customers/password/reset:POST) and [Reset password of Customer in Store](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/password/reset:POST) requests
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      `"The given password token has expired."`

api-specs/api/types/error/graphql/GraphQLExpiredCustomerEmailTokenError.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(package): Error
+type: GraphQLErrorObject
+displayName: GraphQLExpiredCustomerEmailTokenError
+discriminatorValue: ExpiredCustomerEmailToken
+description: |
+  Returned when the provided email token of the Customer has expired.
+
+  The error is returned as a failed response to:
+
+  - [Get Customer by email token](ctp:api:endpoint:/{projectKey}/customers/email-token={emailToken}:GET) and [Get Customer in Store by email token](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/email-token={emailToken}:GET) requests
+  - [Verify email of Customer](ctp:api:endpoint:/{projectKey}/customers/email/confirm:POST) and [Verify email of Customer in Store](ctp:api:endpoint:/{projectKey}/in-store/key={storeKey}/customers/email/confirm:POST) requests
+properties:
+  code:
+    type: string