spree_api 4.3.3 → 4.4.0.rc1

data/docs/oauth/index.yml

@@ -1,4 +1,4 @@
-openapi: 3.0.0
+openapi: 3.0.3
 servers:
   - url: 'https://demo.spreecommerce.org'
     description: demo
@@ -7,7 +7,7 @@ servers:
 info:
   version: 1.0.0
   title: Authentication
-  description: "Spree uses oAuth based Authentication via short-lived Bearer tokens. You can either create a new one or refresh existing token."
+  description: Spree uses oAuth based Authentication via short-lived Bearer tokens. You can either create a new one or refresh existing token.
   contact:
     name: Spark Solutions
     url: 'https://sparksolutions.co'
@@ -18,26 +18,35 @@ info:
 paths:
   /spree_oauth/token:
     post:
-      description: Creates or refreshes a Bearer token required to authorize API calls
-      tags:
-        - Token
-      operationId: Create or Refresh Token
+      description: |-
+        This endpoint creates a new Bearer Token or refreshes an existing Bearer Token.
+
+        The `token` found in the response body is required to authorize API calls.
+      operationId: create-or-refresh-token
       responses:
         '200':
-          description: Token was successfully created or refreshed
+          description: Token was successfully created or refreshed.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Token'
               examples:
-                create token:
+                Storefront User Token:
                   value:
                     access_token: SfM3k8kq5Wkc6xz6rgMlsl-mbygJ1ptq4DR0Ah51vjA
                     token_type: Bearer
                     expires_in: 7200
                     refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
                     created_at: 1581873931
-                refresh token:
+                Platform User Token:
+                  value:
+                    access_token: 2480c16561d1391ea81ca5336b651e9a29f4524f6dee8c7f3f02a600159189c3
+                    token_type: Bearer
+                    expires_in: 7200
+                    refresh_token: f5d78642252eeb3f3001f67b196ac21a27afc030462a54060b0ebbdae2b8dc9c
+                    scope: admin
+                    created_at: 1539863418
+                Refreshed Token:
                   value:
                     access_token: Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98
                     token_type: Bearer
@@ -51,21 +60,57 @@ paths:
             schema:
               oneOf:
                 - $ref: '#/components/schemas/CreateTokenBody'
+                - $ref: '#/components/schemas/ClientTokenBody'
                 - $ref: '#/components/schemas/RefreshTokenBody'
             examples:
-              create token:
+              Create Storefront API User Token:
+                value:
+                  grant_type: password
+                  username: spree@example.com
+                  password: spree123
+              Create Platform API User Token:
                 value:
+                  client_id: 7ZY15L7crVZul8i3PZPrnpOkEURK7xnXEWRZdE6K39M
+                  client_secret: cxMZ0tbe604qj_13hibNmc3GDsXUQfpzHt9PvweihFc
                   grant_type: password
                   username: spree@example.com
                   password: spree123
-              refresh token:
+                  scope: admin
+              Create Platform API Application Token:
+                value:
+                  grant_type: client_credentials
+                  client_id: 7ZY15L7crVZul8i3PZPrnpOkEURK7xnXEWRZdE6K39M
+                  client_secret: cxMZ0tbe604qj_13hibNmc3GDsXUQfpzHt9PvweihFc
+                  scope: admin
+              Refresh a Token:
                 value:
                   grant_type: refresh_token
                   refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
+          application/xml:
+            schema:
+              type: object
+              properties: {}
         description: ''
+      summary: Create or Refresh a Token
+      tags:
+        - Token
 components:
   schemas:
     Token:
+      x-examples:
+        create token:
+          access_token: SfM3k8kq5Wkc6xz6rgMlsl-mbygJ1ptq4DR0Ah51vjA
+          token_type: Bearer
+          expires_in: 7200
+          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
+          created_at: 1581873931
+        refresh token:
+          access_token: Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98
+          token_type: Bearer
+          expires_in: 7200
+          refresh_token: j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY
+          created_at: 1581876572
+      type: object
       properties:
         access_token:
           type: string
@@ -81,34 +126,42 @@ components:
         refresh_token:
           type: string
           example: f5d78642252eeb3f3001f67b196ac21a27afc030462a54060b0ebbdae2b8dc9c
+        scope:
+          type: string
+          example: admin
+          default: admin
         created_at:
           type: integer
           example: 1539863418
-      x-examples:
-        create token:
-          access_token: SfM3k8kq5Wkc6xz6rgMlsl-mbygJ1ptq4DR0Ah51vjA
-          token_type: Bearer
-          expires_in: 7200
-          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
-          created_at: 1581873931
-        refresh token:
-          access_token: Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98
-          token_type: Bearer
-          expires_in: 7200
-          refresh_token: j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY
-          created_at: 1581876572
+      required:
+        - access_token
+        - token_type
+        - expires_in
+        - refresh_token
+        - created_at
+      x-internal: true
     CreateTokenBody:
       type: object
       x-examples:
-        example-1:
+        User Token:
+          grant_type: password
+          username: spree@example.com
+          password: spree123
+        Application Token:
           grant_type: password
           username: spree@example.com
           password: spree123
+          scope: admin
+      x-internal: true
+      title: 'Create a new token (grant_type: password)'
+      description: ''
       properties:
         grant_type:
           type: string
-          default: password
-          description: Use `password` to create a token and `refresh_token` to refresh it
+          description: ''
+          example: password
+          enum:
+            - password
         username:
           type: string
           description: User email address
@@ -117,24 +170,64 @@ components:
           type: string
           description: User password
           example: spree123
+        scope:
+          type: string
+          enum:
+            - admin
+          description: 'Pass the value `admin` to create a Platform User Token, allowing access to the Platform API.'
+          nullable: true
       required:
         - grant_type
         - username
         - password
-    RefreshTokenBody:
+    ClientTokenBody:
       type: object
+      x-examples:
+        example-1:
+          grant_type: refresh_token
+          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
+      x-internal: true
+      title: 'Create a new token (grant_type: client_credentials)'
+      description: ''
       properties:
         grant_type:
           type: string
-          default: refresh_token
-        refresh_token:
+          example: client_credentials
+          enum:
+            - client_credentials
+        client_id:
           type: string
-          description: Refresh token obtained from the create token response
-          example: "27af95fd57a424e5d01aaf5eab1324a8d5c0ca57daf384fae39f811a5144330143301'"
+          description: Use the client id
+          example: 27af95fd57a424e5d01aaf5eab
+        client_secret:
+          type: string
+          example: 1324a8d5c0ca57daf384fae39f811a5144330143301'
+          description: Client secret key.
       required:
         - grant_type
-        - refresh_token
+        - client_id
+        - client_secret
+    RefreshTokenBody:
+      type: object
       x-examples:
         example-1:
           grant_type: refresh_token
           refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
+      x-internal: true
+      title: 'Refresh an existing token (grant_type: refresh_token)'
+      description: ''
+      properties:
+        grant_type:
+          type: string
+          example: refresh_token
+          enum:
+            - refresh_token
+        refresh_token:
+          type: string
+          description: Refresh token obtained from the create token response
+          example: 27af95fd57a424e5d01aaf5eab1324a8d5c0ca57daf384fae39f811a5144330143301'
+      required:
+        - grant_type
+        - refresh_token
+tags:
+  - name: Token