docs: update api docs

discue · Mar 26, 2023 · 39d8c8d · 39d8c8d
1 parent b8715e8
commit 39d8c8d
Show file tree

Hide file tree

Showing 20 changed files with 290 additions and 31 deletions.
diff --git a/docs/api-reference/api-keys/create-an-api-key.md b/docs/api-reference/api-keys/create-an-api-key.md
@@ -22,6 +22,30 @@ api:
 
 **Creates** a new API key and returns the actual key. 
 
+An API Key may have various scopes attached to it. If no scopes get passed
+a default set of scopes will be assigned. **Please note**: By default the
+scopes are very permissive to support a wide range of use cases. 
+
+As an example, a restrictive scope might look like this:
+```json
+  scopes: [{
+    resource: 'listeners',
+    access: 'write',
+    targets: [
+      'MbCS6UB_m7NdvyDOE8stT',
+      'YKOuoR5IIUUWxZeZLKf2O'
+    ]
+  }, {
+    resource: 'queues',
+    access: 'write',
+    targets: '*'
+  }, {
+    resource: 'messages',
+    access: 'read',
+    targets: '*'
+  }]
+```
+
 <Badge type="warning" text="Note" vertical="middle"/> For security reasons, the 
 API key will only be returned once after its creation.
 
@@ -39,22 +63,79 @@ See also: [Authentication](/getting-started/#prerequisites).
 
 ```shell
 curl -X POST http://api.discue.io/v1/api_keys \
+  -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
-  -H 'X-API-KEY: API_KEY'
+  -H 'X-API-KEY: API_KEY' \
+  -d '{
+  "name": "string",
+  "status": "disabled",
+  "scopes": [
+    {
+      "resource": "queues",
+      "access": "write",
+      "targets": [
+        "*"
+      ]
+    },
+    {
+      "resource": "listeners",
+      "access": "write",
+      "targets": [
+        "_Tzrg1O3jk4_FZTAEThNq"
+      ]
+    },
+    {
+      "resource": "messages",
+      "access": "read",
+      "targets": [
+        "*"
+      ]
+    }
+  ]
+}' 
 ```
 
 </CodeGroupItem>
 
 <CodeGroupItem title="javascript">
 
 ```javascript
+const body = {
+  "name": "string",
+  "status": "disabled",
+  "scopes": [
+    {
+      "resource": "queues",
+      "access": "write",
+      "targets": [
+        "*"
+      ]
+    },
+    {
+      "resource": "listeners",
+      "access": "write",
+      "targets": [
+        "_Tzrg1O3jk4_FZTAEThNq"
+      ]
+    },
+    {
+      "resource": "messages",
+      "access": "read",
+      "targets": [
+        "*"
+      ]
+    }
+  ]
+}
+
 const headers = {
+  'Content-Type':'application/json',
   'Accept':'application/json',
   'X-API-KEY':'API_KEY'
 }
 
 const response = await fetch('http://api.discue.io/v1/api_keys', {
-  method: 'POST',  headers
+  method: 'POST',  body,  headers
 })
 
 const body = await response.json()
@@ -67,6 +148,7 @@ const body = await response.json()
 ```python
 import requests
 headers = {
+  'Content-Type': 'application/json',
   'Accept': 'application/json',
   'X-API-KEY': 'API_KEY'
 }
@@ -89,6 +171,7 @@ import (
 func main() {
 
   headers := map[string][]string{
+      "Content-Type": []string{"application/json"},
       "Accept": []string{"application/json"},
       "X-API-KEY": []string{"API_KEY"},
   }
@@ -106,10 +189,70 @@ func main() {
 
 </CodeGroup>
 
+## Body
+
+```json
+{
+  "name": "string",
+  "status": "disabled",
+  "scopes": [
+    {
+      "resource": "queues",
+      "access": "write",
+      "targets": [
+        "*"
+      ]
+    },
+    {
+      "resource": "listeners",
+      "access": "write",
+      "targets": [
+        "_Tzrg1O3jk4_FZTAEThNq"
+      ]
+    },
+    {
+      "resource": "messages",
+      "access": "read",
+      "targets": [
+        "*"
+      ]
+    }
+  ]
+}
+```
+
 ## Parameters 
 |Name|In|Type|Required|Description|
 |---|---|---|---|---|
 |pretty|query|boolean| ❌ |Return the response pretty printed|
+|body|body|[PostApiKeyRequest](#schemapostapikeyrequest)| ❌ |none|
+|» name|body|[ResourceName](#resourcename)| ❌ |none|
+|» status|body|string| ❌ |none|
+|» scopes|body|[ApiKeyScope](#apikeyscope)| ❌ |none|
+|»» resource|body|string| ❌ |none|
+|»» access|body|string| ❌ |none|
+|»» targets|body|any| ❌ |none|
+|»»» *anonymous*|body|[ResourceId](#resourceid)| ❌ |none|
+|»»» *anonymous*|body|string| ❌ |none|
+
+## Enumerated Values
+
+|Parameter|Value|
+|---|---|
+|» status|disabled|
+|» status|enabled|
+|»» resource|api_clients|
+|»» resource|api_keys|
+|»» resource|events|
+|»» resource|queues|
+|»» resource|listeners|
+|»» resource|messages|
+|»» resource|schemas|
+|»» resource|stats|
+|»» resource|subscriptions|
+|»» access|read|
+|»» access|write|
+|»»» *anonymous*|*|
 
 ## Responses 
 

diff --git a/docs/api-reference/api-keys/delete-an-api-key-by-id.md b/docs/api-reference/api-keys/delete-an-api-key-by-id.md
@@ -117,7 +117,7 @@ func main() {
 ## Parameters 
 |Name|In|Type|Required|Description|
 |---|---|---|---|---|
-|api_key_id|path|string(uuid)|✔|Id of the api key|
+|api_key_id|path|[ResourceId](#schemaresourceid)|✔|Id of the api key|
 |pretty|query|boolean| ❌ |Return the response pretty printed|
 
 ## Responses 

diff --git a/docs/api-reference/api-keys/get-all-api-keys.md b/docs/api-reference/api-keys/get-all-api-keys.md
@@ -130,7 +130,16 @@ func main() {
       "updated_at": 1644616838173,
       "last_used_at": 1644616838173,
       "key": "ep1",
-      "status": "disabled"
+      "status": "disabled",
+      "scopes": [
+        {
+          "resource": "queues",
+          "access": "write",
+          "targets": [
+            "_A36cABAOqhBdNeZeXB0l"
+          ]
+        }
+      ]
     }
   ],
   "_links": {

diff --git a/docs/api-reference/api-keys/get-an-api-key-by-id.md b/docs/api-reference/api-keys/get-an-api-key-by-id.md
@@ -117,7 +117,7 @@ func main() {
 ## Parameters 
 |Name|In|Type|Required|Description|
 |---|---|---|---|---|
-|api_key_id|path|string(uuid)|✔|Id of the api key|
+|api_key_id|path|[ResourceId](#schemaresourceid)|✔|Id of the api key|
 |pretty|query|boolean| ❌ |Return the response pretty printed|
 
 ## Responses 
@@ -134,7 +134,16 @@ func main() {
     "updated_at": 1644616838173,
     "last_used_at": 1644616838173,
     "key": "ep1",
-    "status": "disabled"
+    "status": "disabled",
+    "scopes": [
+      {
+        "resource": "queues",
+        "access": "write",
+        "targets": [
+          "_A36cABAOqhBdNeZeXB0l"
+        ]
+      }
+    ]
   },
   "_links": {
     "self": {