diff --git a/openapi.yaml b/openapi.yaml
index b33d8dc..e6116ef 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -38,6 +38,7 @@ servers:
           - dev
 security:
   - apiKey: []
+  - bearerAuth: []
 tags:
   - name: drinks
     description: The drinks endpoints.
@@ -57,22 +58,33 @@ paths:
       - 5XX
   /authenticate:
     post:
-      operationId: authenticate
+      operationId: login
       summary: Authenticate with the API by providing a username and password.
-      security: []
+      security:
+        - basicHttp: []
       tags:
         - authentication
+      x-speakeasy-usage-example:
+        title: "Sign in"
+        description: |-
+          First you need to send an authentication request to the API by providing your username and password.
+          In the request body, you should specify the type of token you would like to receive: API key or JSON Web Token.
+          If your credentials are valid, you will receive a token in the response object: `res.object.token: str`.
+        position: 1
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
+              required:
+                - type
               properties:
-                username:
-                  type: string
-                password:
+                type:
                   type: string
+                  enum:
+                    - apiKey
+                    - JWT
       responses:
         "200":
           description: The api key to use for authenticated endpoints.
@@ -89,15 +101,23 @@ paths:
           $ref: "#/components/responses/APIError"
         default:
           $ref: "#/components/responses/UnknownError"
-
   /drinks:
     get:
-      x-speakeasy-usage-example: true
       operationId: listDrinks
       summary: Get a list of drinks.
       description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
       security:
+        - bearerAuth: []
         - {}
+      x-speakeasy-usage-example:
+        title: "Browse available drinks"
+        description: |-
+          Once you are authenticated, you can use the token you received for all other authenticated endpoints.
+          For example, you can filter the list of available drinks by type.
+        position: 2
+      servers:
+        - url: https://speakeasy.bar
+        - url: https://test.speakeasy.bar
       tags:
         - drinks
       parameters:
@@ -120,7 +140,6 @@ paths:
           $ref: "#/components/responses/APIError"
         default:
           $ref: "#/components/responses/UnknownError"
-
   /drink/{name}: #TODO: this should be by product code and we should have search by name
     get:
       operationId: getDrink
@@ -151,6 +170,16 @@ paths:
       operationId: listIngredients
       summary: Get a list of ingredients.
       description: Get a list of ingredients, if authenticated this will include stock levels and product codes otherwise it will only include public information.
+      x-speakeasy-usage-example:
+        description: |-
+          Specifying tags for this extension allows selecting the operation for specific README sections.
+          If the "tags" array is not provided or if it contains the tag "usage", a usage snippet associated
+          with the operation will be inserted in the main "SDK Example Usage" section. In this case a "title"
+          and "description" can be provided for this example and its relative positioning can be set through
+          the "position" attribute. "title", "description" and "position" have no effect for other tags.
+        tags:
+          - server  # Server Selection
+          - security # Authentication
       tags:
         - ingredients
       parameters:
@@ -185,6 +214,12 @@ paths:
       description: Create an order for a drink.
       tags:
         - orders
+      x-speakeasy-usage-example:
+        title: "Create an order"
+        description: |-
+          When you submit an order, you can include a callback URL along your request.
+          This URL will get called whenever the supplier updates the status of your order.
+        position: 3
       parameters:
         - name: callback_url
           in: query
@@ -242,6 +277,23 @@ paths:
       description: Subscribe to webhooks.
       tags:
         - config
+      x-speakeasy-usage-example:
+        title: "Subscribe to webhooks to receive stock updates"
+        position: 3
+        tags:
+          - usage    # SDK Example Usage
+          - retries  # Retries
+          - errors   # Error Handling
+      x-speakeasy-retries:
+        strategy: backoff
+        backoff:
+          initialInterval: 10 # 10 ms
+          maxInterval: 200 # 200 ms
+          maxElapsedTime: 1000 # 1 seconds
+          exponent: 1.5
+        statusCodes:
+          - 404
+        retryConnectionErrors: false
       requestBody:
         required: true
         content:
@@ -260,6 +312,8 @@ paths:
       responses:
         "200":
           description: The webhook was subscribed to successfully.
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "5XX":
           $ref: "#/components/responses/APIError"
         default:
@@ -299,9 +353,25 @@ components:
           type: string
         message:
           type: string
+          x-speakeasy-error-message: true
         details:
           type: object
           additionalProperties: true
+    BadRequest:
+      type: object
+      properties:
+        status_code:
+          type: number
+          description: HTTP status code
+          example: 400
+        error:
+          type: string
+          description: Contains an explanation of the status_code as defined in HTTP/1.1 standard (RFC 7231)
+          example: Bad Request
+        type_name:
+          type: string
+          description: The type of error returned
+          example: RequestValidationError
     Error:
       type: object
       properties:
@@ -430,6 +500,15 @@ components:
       type: apiKey
       name: Authorization
       in: header
+      x-speakeasy-example: <YOUR_API_KEY>
+    bearerAuth:
+      type: http
+      scheme: bearer
+      x-speakeasy-example: <YOUR_JWT>
+    basicHttp:
+      type: http
+      scheme: basic
+      x-speakeasy-example: <USERNAME>;<PASSWORD>
   responses:
     APIError:
       description: An error occurred interacting with the API.
@@ -437,9 +516,15 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/APIError"
+    BadRequest:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/BadRequest"
     UnknownError:
       description: An unknown error occurred interacting with the API.
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/Error"
\ No newline at end of file
+            $ref: "#/components/schemas/Error"