Merge pull request #334 from reshmabidikar/work-for-333

Auth API documentation
killbill · Feb 5, 2025 · 7128e30 · 7128e30
2 parents 15c2395 + 6337e3f
commit 7128e30
Show file tree

Hide file tree

Showing 29 changed files with 148 additions and 0 deletions.
diff --git a/source/account.html.md b/source/account.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/admin.html.md b/source/admin.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/auth.html.md b/source/auth.html.md
@@ -0,0 +1,50 @@
+---
+includes: 
+  - aviate-catalog
+
+current_page: aviate-catalog
+
+menu_items:
+  - index
+  - tenant
+  - catalog
+  - account
+  - payment-method
+  - subscription
+  - bundle
+  - invoice
+  - invoice-item
+  - credit
+  - payment
+  - payment-transaction
+  - invoice-payment
+  - usage
+  - custom-field
+  - tag
+  - tag-definition
+  - export
+  - admin
+  - security
+  - aviate-auth
+  - aviate-catalog
+  - aviate-health
+  - aviate-metering
+
+title: Kill Bill
+
+language_tabs:
+   - shell
+   - java
+   - ruby
+   - python
+   - javascript
+   - php
+
+toc_footers:
+  - <a href="mailto:[email protected]">Report a doc problem </a>
+
+search: true
+
+code_clipboard: true
+
+---
diff --git a/source/aviate-catalog.html.md b/source/aviate-catalog.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/aviate-health.html.md b/source/aviate-health.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/aviate-metering.html.md b/source/aviate-metering.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/bundle.html.md b/source/bundle.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/catalog.html.md b/source/catalog.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/credit.html.md b/source/credit.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/custom-field.html.md b/source/custom-field.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/export.html.md b/source/export.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/includes/_aviate-auth.md b/source/includes/_aviate-auth.md
@@ -0,0 +1,59 @@
+# Aviate Auth
+
+The Aviate Plugin uses a JWT based authentication mechanism. Thus, a valid JWT is required to access all APIs.
+
+## Auth API
+
+The Auth API generates a JWT for authenticating with the Aviate Plugin. This token must be included in the Authorization header for subsequent API requests. Note that the Auth API must be invoked with an email and password in order to generate the JWT.
+
+**HTTP Request**
+
+`POST /plugins/aviate-plugin/v1/auth`
+
+> Example Request:
+
+```shell
+curl -X POST \
+    -H 'Content-Type: application/json' \
+    -u "<email>:<password>" \
+    -H 'X-killbill-apiKey: alphaF' \
+    -H 'X-killbill-apisecret: alphaF' \
+    'http://127.0.0.1:8080/plugins/aviate-plugin/v1/auth'
+```
+
+```java
+```
+
+```ruby
+```
+
+```python
+```
+
+````php
+````
+
+````javacript
+````
+
+> Example Response:
+
+````json
+{
+  "token": "eyJraWQiOiJmSGs3ZkIyQzNlc25EUXdVV0xRM2VYeldpWlVIcVRzd0dpT2cyU2Nnb25FPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJmY2Y1NzhjMy01OGVmLTQ3N2YtYTcxNC1lZDU5NmZjZTliNmMiLCJwcm9kdWN0IjoiQXZpYXRlLUZsb2NrIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbVwvdXMtd2VzdC0yX1ZFb2NJVkFNdCIsImNvZ25pdG86dXNlcm5hbWUiOiJmY2Y1NzhjMy01OGVmLTQ3N2YtYTcxNC1lZDU5NmZjZTliNmMiLCJvcmlnaW5fanRpIjoiNjhmMGEwMDgtMmNmZS00YzM4LTg4ZDItZjA0MzM1ODk0ODNhIiwiZmVhdHVyZXMiOiJwYWlkLXBsYW5zLG9yZ3MtYWNjZXNzLHBsdWdpbi1pbnN0YWxsLGFwcC1hZG1pbixhcHAtaGVhbHRoLGFwcC1xdW90ZSxhcHAtYmkiLCJhdWQiOiIzdG0xcjYxY3B0dTMxaGc5MGNlMTdlMHBzIiwiZXZlbnRfaWQiOiIxY2Y2MjdkNS0zZjg0LTRjZTktYjM2NC0zM2ZhMzc3MTRlODkiLCJ0b2tlbl91c2UiOiJpZCIsImF1dGhfdGltZSI6MTczNzcwNTY5MiwiY3VzdG9tOmJhX2lkIjoiY3VzX05aQXd0TlpCNkxpUmJNIiwiZXhwIjoxNzM3NzA5MjkxLCJpYXQiOjE3Mzc3MDU2OTIsImp0aSI6IjEzMGQ2ZmM3LTU2MGItNDQ3My04YTVlLTIxNzliY2ZkOWIwNCIsImVtYWlsIjoicmVzaDEyM0BnbWFpbC5jb20ifQ.S2CPMIq6zQ3QkOObeYR-jFL67kx3i8i6bSCjUy4SMr3DapBaqjU_q1qettvZ75pHQK0-JxTvSucw14CvDmBikEHyQDv043tIFL2POA0-GvxFdnNzOLEfbeu338ZxWyodGUg-x41HmYG8Q0DEAa0CbZiaj-sI3YMTOB9dRW5UHxSCy7LPpzaNd_ZRB0_MatzTbBgesSMowz9kJMyhnSCKRJLtazdzeNXapij9pg50paasMZPqlqPvvFrc5zHNRUTF84tN19cdvvmj87qZDFMMoc0X8GihrmgqsI6eJ3vAKiECwoeRKPJwHioFxu8Id9atV_1jRoSS-owULkFnfIKDSQ"
+}
+````
+
+**Request Body**
+
+None
+
+
+**Query Parameters**
+
+None
+
+
+**Response**
+
+If successful, returns a status code of 200 and a JSON String with the token.
diff --git a/source/includes/_aviate-catalog.md b/source/includes/_aviate-catalog.md
@@ -18,6 +18,10 @@ Product, plan, and pricelist resources are uniquely identified by the tuple {ten
 
 At the time of writing, the aviate catalog plugin does not expose any endpoints for catalog retrieval. Instead, the catalog can be retrieved via the [KB Catalog APIs](https://apidocs.killbill.io/catalog).
 
+### Authentication
+
+The Aviate Plugin uses a JWT based authentication mechanism. Thus, all the APIs listed in this document require a valid token. This can be obtained via the [Auth API](aviate_auth.html#auth_api). 
+
 ## Resources
 
 This section lists the models used by the Catalog APIs

diff --git a/source/includes/_aviate-health.md b/source/includes/_aviate-health.md
@@ -2,6 +2,12 @@
 
 The [Aviate Health feature](https://docs.killbill.io/latest/aviate-health) provides several endpoints that allow you to view the health of your KillBill system and fix problems if any. This section documents the APIs exposed by the Aviate Health feature.
 
+## Before You Begin
+
+### Authentication
+
+The Aviate Plugin uses a JWT based authentication mechanism. Thus, all the APIs listed in this document require a valid token. This can be obtained via the [Auth API](aviate_auth.html#auth_api).
+
 ## Resources
 
 ### MetricsResult

diff --git a/source/includes/_aviate-metering.md b/source/includes/_aviate-metering.md
@@ -2,6 +2,12 @@
 
 The Aviate plugin offers a metering feature that allows performing usage aggregation. As part of this functionality, the plugin exposes some metering APIs. These APIs provide the ability to create billing meters and record usage data against these meters. This section documents the metering APIs exported by the Aviate plugin.
 
+## Before You Begin
+
+### Authentication
+
+The Aviate Plugin uses a JWT based authentication mechanism. Thus, all the APIs listed in this document require a valid token. This can be obtained via the [Auth API](aviate_auth.html#auth_api).
+
 ## Resources
 
 ### BillingMeter

diff --git a/source/includes/_aviate_auth.md b/source/includes/_aviate_auth.md
diff --git a/source/index.html.md b/source/index.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/invoice-item.html.md b/source/invoice-item.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/invoice-payment.html.md b/source/invoice-payment.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/invoice.html.md b/source/invoice.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/payment-method.html.md b/source/payment-method.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/payment-transaction.html.md b/source/payment-transaction.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/payment.html.md b/source/payment.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/security.html.md b/source/security.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/subscription.html.md b/source/subscription.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/tag-definition.html.md b/source/tag-definition.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/tag.html.md b/source/tag.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/tenant.html.md b/source/tenant.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering

diff --git a/source/usage.html.md b/source/usage.html.md
@@ -25,6 +25,7 @@ menu_items:
   - export
   - admin
   - security
+  - aviate-auth
   - aviate-catalog
   - aviate-health
   - aviate-metering