diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 6df4421e..25c4a727 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -141,7 +141,7 @@ export default withMermaid(defineConfig({ nav: [ { text: 'Self-hosting', link: '/self-hosting/overview' }, { text: 'API Reference', link: '/api-reference/introduction' }, - { text: 'Build and extend', link: '/dev-tools/build-plane-app' }, + { text: 'Build and extend', link: '/dev-tools/build-plane-app/overview' }, { text: 'Plane Docs', link: 'https://docs.plane.so' }, { text: 'Sign in', link: 'https://app.plane.so/sign-in' } ], @@ -649,7 +649,17 @@ export default withMermaid(defineConfig({ { text: 'Build and extend Plane', items: [ - { text: 'Build Plane App', link: '/dev-tools/build-plane-app' }, + { + text: 'Build Plane App', collapsed: false, items: [ + { text: 'Overview', link: '/dev-tools/build-plane-app/overview' }, + { text: 'Create an OAuth application', link: '/dev-tools/build-plane-app/create-oauth-application' }, + { text: 'Choose token Flow', link: '/dev-tools/build-plane-app/choose-token-flow' }, + { text: 'Handling webhooks', link: '/dev-tools/build-plane-app/webhooks' }, + { text: 'OAuth scopes', link: '/dev-tools/build-plane-app/oauth-scopes' }, + { text: 'SDKs', link: '/dev-tools/build-plane-app/sdks' }, + { text: 'Complete examples', link: '/dev-tools/build-plane-app/examples' } + ] + }, { text: 'Agents', collapsed: false, diff --git a/docs/api-reference/customer/add-customer-property.md b/docs/api-reference/customer/add-customer-property.md index 83033261..13b0a904 100644 --- a/docs/api-reference/customer/add-customer-property.md +++ b/docs/api-reference/customer/add-customer-property.md @@ -131,6 +131,14 @@ External ID from the external source. +
+ +### Scopes + +`customers.properties:write` + +
+
@@ -141,6 +149,7 @@ External ID from the external source. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/customer-properties/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", @@ -241,3 +250,4 @@ const data = await response.json();
+ diff --git a/docs/api-reference/customer/add-customer-request.md b/docs/api-reference/customer/add-customer-request.md index 9048686b..64a194b6 100644 --- a/docs/api-reference/customer/add-customer-request.md +++ b/docs/api-reference/customer/add-customer-request.md @@ -59,6 +59,14 @@ Description of the request. +
+ +### Scopes + +`customers.requests:write` + +
+
@@ -69,6 +77,7 @@ Description of the request. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/requests/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "example-title", diff --git a/docs/api-reference/customer/add-customer.md b/docs/api-reference/customer/add-customer.md index 5ed4c9d7..a8530c5f 100644 --- a/docs/api-reference/customer/add-customer.md +++ b/docs/api-reference/customer/add-customer.md @@ -53,6 +53,14 @@ Email address of the customer.
+
+ +### Scopes + +`customers:write` + +
+
@@ -63,6 +71,7 @@ Email address of the customer. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/customer/delete-customer-property.md b/docs/api-reference/customer/delete-customer-property.md index 8726460b..8762c52a 100644 --- a/docs/api-reference/customer/delete-customer-property.md +++ b/docs/api-reference/customer/delete-customer-property.md @@ -38,6 +38,14 @@ The unique identifier for the customer property.
+
+ +### Scopes + +`customers.properties:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the customer property. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/customer-properties/{property_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/delete-customer-request.md b/docs/api-reference/customer/delete-customer-request.md index 76fc4667..42e2844a 100644 --- a/docs/api-reference/customer/delete-customer-request.md +++ b/docs/api-reference/customer/delete-customer-request.md @@ -44,6 +44,14 @@ The unique identifier for the request.
+
+ +### Scopes + +`customers.requests:write` + +
+
@@ -54,6 +62,7 @@ The unique identifier for the request. curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/requests/{request_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/delete-customer.md b/docs/api-reference/customer/delete-customer.md index a4ffd9b0..a7622d7a 100644 --- a/docs/api-reference/customer/delete-customer.md +++ b/docs/api-reference/customer/delete-customer.md @@ -38,6 +38,14 @@ The unique identifier for the customer.
+
+ +### Scopes + +`customers:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the customer. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/get-customer-detail.md b/docs/api-reference/customer/get-customer-detail.md index e2907e76..a6c4cee2 100644 --- a/docs/api-reference/customer/get-customer-detail.md +++ b/docs/api-reference/customer/get-customer-detail.md @@ -38,6 +38,14 @@ The unique identifier for the customer.
+
+ +### Scopes + +`customers:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the customer. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/get-customer-property-detail.md b/docs/api-reference/customer/get-customer-property-detail.md index cba63d39..781513e0 100644 --- a/docs/api-reference/customer/get-customer-property-detail.md +++ b/docs/api-reference/customer/get-customer-property-detail.md @@ -38,6 +38,14 @@ The unique identifier for the customer property.
+
+ +### Scopes + +`customers.properties:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the customer property. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customer-properties/{property_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/get-customer-property-value.md b/docs/api-reference/customer/get-customer-property-value.md index 03c6b8bf..9ad79eb0 100644 --- a/docs/api-reference/customer/get-customer-property-value.md +++ b/docs/api-reference/customer/get-customer-property-value.md @@ -44,6 +44,14 @@ The unique identifier for the customer property.
+
+ +### Scopes + +`customers.property_values:read` + +
+
@@ -54,6 +62,7 @@ The unique identifier for the customer property. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/property-values/{property_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/get-customer-request-detail.md b/docs/api-reference/customer/get-customer-request-detail.md index 512b7fc0..06c5b486 100644 --- a/docs/api-reference/customer/get-customer-request-detail.md +++ b/docs/api-reference/customer/get-customer-request-detail.md @@ -44,6 +44,14 @@ The unique identifier for the request.
+
+ +### Scopes + +`customers.requests:read` + +
+
@@ -54,6 +62,7 @@ The unique identifier for the request. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/requests/{request_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/link-work-items-to-customer.md b/docs/api-reference/customer/link-work-items-to-customer.md index 7a4b0f5f..d31dd2be 100644 --- a/docs/api-reference/customer/link-work-items-to-customer.md +++ b/docs/api-reference/customer/link-work-items-to-customer.md @@ -53,6 +53,14 @@ Array of work item IDs to link to the customer.
+
+ +### Scopes + +`customers.work_items:write` + +
+
@@ -63,6 +71,7 @@ Array of work item IDs to link to the customer. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/work-items/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issue_ids": "example-issue_ids" diff --git a/docs/api-reference/customer/list-customer-properties.md b/docs/api-reference/customer/list-customer-properties.md index 9826f492..6748fe4d 100644 --- a/docs/api-reference/customer/list-customer-properties.md +++ b/docs/api-reference/customer/list-customer-properties.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`customers.properties:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customer-properties/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/list-customer-property-values.md b/docs/api-reference/customer/list-customer-property-values.md index b36b0ab1..2ccd40f9 100644 --- a/docs/api-reference/customer/list-customer-property-values.md +++ b/docs/api-reference/customer/list-customer-property-values.md @@ -77,6 +77,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`customers.property_values:read` + +
+
@@ -86,7 +94,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/property-values/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/list-customer-requests.md b/docs/api-reference/customer/list-customer-requests.md index 00088acf..5b634cfd 100644 --- a/docs/api-reference/customer/list-customer-requests.md +++ b/docs/api-reference/customer/list-customer-requests.md @@ -71,6 +71,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`customers.requests:read` + +
+
@@ -80,7 +88,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/requests/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/list-customer-work-items.md b/docs/api-reference/customer/list-customer-work-items.md index 8d31a08c..190ed162 100644 --- a/docs/api-reference/customer/list-customer-work-items.md +++ b/docs/api-reference/customer/list-customer-work-items.md @@ -38,6 +38,14 @@ The unique identifier for the customer.
+
+ +### Scopes + +`customers.work_items:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the customer. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/work-items/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/list-customers.md b/docs/api-reference/customer/list-customers.md index 0a1fc6a5..da77a1d6 100644 --- a/docs/api-reference/customer/list-customers.md +++ b/docs/api-reference/customer/list-customers.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`customers:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/unlink-work-item-from-customer.md b/docs/api-reference/customer/unlink-work-item-from-customer.md index afdc3a5f..1a7be8ec 100644 --- a/docs/api-reference/customer/unlink-work-item-from-customer.md +++ b/docs/api-reference/customer/unlink-work-item-from-customer.md @@ -44,6 +44,14 @@ The unique identifier for the work item.
+
+ +### Scopes + +`customers.work_items:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the work item. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/work-items/work-item-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/customer/update-customer-detail.md b/docs/api-reference/customer/update-customer-detail.md index 15b12194..5f6a0c40 100644 --- a/docs/api-reference/customer/update-customer-detail.md +++ b/docs/api-reference/customer/update-customer-detail.md @@ -59,6 +59,14 @@ Email address of the customer.
+
+ +### Scopes + +`customers:write` + +
+
@@ -69,6 +77,7 @@ Email address of the customer. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/customer/update-customer-property-detail.md b/docs/api-reference/customer/update-customer-property-detail.md index ee98be22..3d824b4b 100644 --- a/docs/api-reference/customer/update-customer-property-detail.md +++ b/docs/api-reference/customer/update-customer-property-detail.md @@ -137,6 +137,14 @@ External ID from the external source.
+
+ +### Scopes + +`customers.properties:write` + +
+
@@ -147,6 +155,7 @@ External ID from the external source. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/customer-properties/{property_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/customer/update-customer-property-value.md b/docs/api-reference/customer/update-customer-property-value.md index 64c07e58..037874ca 100644 --- a/docs/api-reference/customer/update-customer-property-value.md +++ b/docs/api-reference/customer/update-customer-property-value.md @@ -59,6 +59,14 @@ Array of values to set for the property.
+
+ +### Scopes + +`customers.property_values:write` + +
+
@@ -69,6 +77,7 @@ Array of values to set for the property. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/property-values/{property_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "values": "example-values" diff --git a/docs/api-reference/customer/update-customer-request-detail.md b/docs/api-reference/customer/update-customer-request-detail.md index 37cd4ec2..fc8c4ce5 100644 --- a/docs/api-reference/customer/update-customer-request-detail.md +++ b/docs/api-reference/customer/update-customer-request-detail.md @@ -65,6 +65,14 @@ Description of the request.
+
+ +### Scopes + +`customers.requests:write` + +
+
@@ -75,6 +83,7 @@ Description of the request. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/customers/{customer_id}/requests/{request_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "example-title", diff --git a/docs/api-reference/cycle/add-cycle-work-items.md b/docs/api-reference/cycle/add-cycle-work-items.md index 41cdc5ca..9bcace73 100644 --- a/docs/api-reference/cycle/add-cycle-work-items.md +++ b/docs/api-reference/cycle/add-cycle-work-items.md @@ -59,6 +59,14 @@ Array of work item IDs to add to the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -69,6 +77,7 @@ Array of work item IDs to add to the cycle. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/cycle-issues/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issues": "example-issues" diff --git a/docs/api-reference/cycle/add-cycle.md b/docs/api-reference/cycle/add-cycle.md index 2b4d46b2..e8b1ac55 100644 --- a/docs/api-reference/cycle/add-cycle.md +++ b/docs/api-reference/cycle/add-cycle.md @@ -101,6 +101,14 @@ ID of the project for the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -111,6 +119,7 @@ ID of the project for the cycle. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/cycle/archive-cycle.md b/docs/api-reference/cycle/archive-cycle.md index 482f507e..9d25f706 100644 --- a/docs/api-reference/cycle/archive-cycle.md +++ b/docs/api-reference/cycle/archive-cycle.md @@ -44,6 +44,14 @@ The unique identifier for the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the cycle. ```bash curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/archived-cycles/cycle-uuid/archive/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/delete-cycle.md b/docs/api-reference/cycle/delete-cycle.md index 13e90819..cbcf1aee 100644 --- a/docs/api-reference/cycle/delete-cycle.md +++ b/docs/api-reference/cycle/delete-cycle.md @@ -44,6 +44,14 @@ The unique identifier for the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the cycle. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/get-cycle-detail.md b/docs/api-reference/cycle/get-cycle-detail.md index 6655e392..2c0bf428 100644 --- a/docs/api-reference/cycle/get-cycle-detail.md +++ b/docs/api-reference/cycle/get-cycle-detail.md @@ -44,6 +44,14 @@ The unique identifier for the cycle.
+
+ +### Scopes + +`projects.cycles:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the cycle. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/list-archived-cycles.md b/docs/api-reference/cycle/list-archived-cycles.md index 6b88d740..75d89b48 100644 --- a/docs/api-reference/cycle/list-archived-cycles.md +++ b/docs/api-reference/cycle/list-archived-cycles.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.cycles:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/archived-cycles/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/list-cycle-work-items.md b/docs/api-reference/cycle/list-cycle-work-items.md index b8e635df..e85ee3de 100644 --- a/docs/api-reference/cycle/list-cycle-work-items.md +++ b/docs/api-reference/cycle/list-cycle-work-items.md @@ -44,6 +44,14 @@ The unique identifier for the cycle.
+
+ +### Scopes + +`projects.cycles:read` `projects.work_items:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the cycle. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/cycle-issues/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/list-cycles.md b/docs/api-reference/cycle/list-cycles.md index ee222a9c..c0819b5e 100644 --- a/docs/api-reference/cycle/list-cycles.md +++ b/docs/api-reference/cycle/list-cycles.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.cycles:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/remove-cycle-work-item.md b/docs/api-reference/cycle/remove-cycle-work-item.md index dfa3d74e..c4bdda4e 100644 --- a/docs/api-reference/cycle/remove-cycle-work-item.md +++ b/docs/api-reference/cycle/remove-cycle-work-item.md @@ -50,6 +50,14 @@ The unique identifier for the work item.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the work item. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/cycle-issues/issue-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/transfer-cycle-work-items.md b/docs/api-reference/cycle/transfer-cycle-work-items.md index d2fc2014..08b279fe 100644 --- a/docs/api-reference/cycle/transfer-cycle-work-items.md +++ b/docs/api-reference/cycle/transfer-cycle-work-items.md @@ -59,6 +59,14 @@ ID of the target cycle to transfer work items to.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -69,6 +77,7 @@ ID of the target cycle to transfer work items to. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/transfer-issues/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "new_cycle_id": "example-new_cycle_id" diff --git a/docs/api-reference/cycle/unarchive-cycle.md b/docs/api-reference/cycle/unarchive-cycle.md index d7d0658d..5d96c356 100644 --- a/docs/api-reference/cycle/unarchive-cycle.md +++ b/docs/api-reference/cycle/unarchive-cycle.md @@ -44,6 +44,14 @@ The unique identifier for the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the cycle. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/archived-cycles/cycle-uuid/unarchive/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/cycle/update-cycle-detail.md b/docs/api-reference/cycle/update-cycle-detail.md index 6349c77a..ccb41ba7 100644 --- a/docs/api-reference/cycle/update-cycle-detail.md +++ b/docs/api-reference/cycle/update-cycle-detail.md @@ -101,6 +101,14 @@ Timezone for the cycle.
+
+ +### Scopes + +`projects.cycles:write` + +
+
@@ -111,6 +119,7 @@ Timezone for the cycle. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/cycles/cycle-uuid/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/epics/get-epic-detail.md b/docs/api-reference/epics/get-epic-detail.md index c16e86d6..04775ce2 100644 --- a/docs/api-reference/epics/get-epic-detail.md +++ b/docs/api-reference/epics/get-epic-detail.md @@ -44,6 +44,14 @@ The unique identifier for the epic.
+
+ +### Scopes + +`projects.epics:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the epic. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/epics/{epic_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/epics/list-epics.md b/docs/api-reference/epics/list-epics.md index d3860b76..fc88518a 100644 --- a/docs/api-reference/epics/list-epics.md +++ b/docs/api-reference/epics/list-epics.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`projects.epics:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/epics/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/inbox-issue/add-inbox-issue.md b/docs/api-reference/inbox-issue/add-inbox-issue.md index 27d0f42f..8a27c4ec 100644 --- a/docs/api-reference/inbox-issue/add-inbox-issue.md +++ b/docs/api-reference/inbox-issue/add-inbox-issue.md @@ -53,6 +53,14 @@ An object containing the issue details, including a `name` field (required).
+
+ +### Scopes + +`projects.intakes:write` + +
+
@@ -63,6 +71,7 @@ An object containing the issue details, including a `name` field (required). curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/inbox-issues/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issue": "example-issue" diff --git a/docs/api-reference/inbox-issue/delete-inbox-issue.md b/docs/api-reference/inbox-issue/delete-inbox-issue.md index ede0f218..b4130e8c 100644 --- a/docs/api-reference/inbox-issue/delete-inbox-issue.md +++ b/docs/api-reference/inbox-issue/delete-inbox-issue.md @@ -50,6 +50,14 @@ Deletes an intake issue
+
+ +### Scopes + +`projects.intakes:write` + +
+
@@ -59,7 +67,8 @@ Deletes an intake issue ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/inbox-issues/issue-uuid" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/inbox-issue/get-inbox-issue-detail.md b/docs/api-reference/inbox-issue/get-inbox-issue-detail.md index 89d0e615..895afd11 100644 --- a/docs/api-reference/inbox-issue/get-inbox-issue-detail.md +++ b/docs/api-reference/inbox-issue/get-inbox-issue-detail.md @@ -44,6 +44,14 @@ Gets the details of an intake issue
+
+ +### Scopes + +`projects.intakes:read` + +
+
@@ -53,7 +61,8 @@ Gets the details of an intake issue ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/inbox-issues/issue-uuid" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/inbox-issue/list-inbox-issues.md b/docs/api-reference/inbox-issue/list-inbox-issues.md index 5903e102..f3211cf4 100644 --- a/docs/api-reference/inbox-issue/list-inbox-issues.md +++ b/docs/api-reference/inbox-issue/list-inbox-issues.md @@ -38,6 +38,14 @@ Gets all the intake issue of a project
+
+ +### Scopes + +`projects.intakes:read` + +
+
@@ -47,7 +55,8 @@ Gets all the intake issue of a project ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/inbox-issues/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/inbox-issue/update-inbox-issue-detail.md b/docs/api-reference/inbox-issue/update-inbox-issue-detail.md index f9e1fc17..c419599b 100644 --- a/docs/api-reference/inbox-issue/update-inbox-issue-detail.md +++ b/docs/api-reference/inbox-issue/update-inbox-issue-detail.md @@ -59,6 +59,14 @@ An object containing the issue details to update, including an optional `name` f
+
+ +### Scopes + +`projects.intakes:write` + +
+
@@ -69,6 +77,7 @@ An object containing the issue details to update, including an optional `name` f curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/inbox-issues/issue-uuid" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issue": "example-issue" diff --git a/docs/api-reference/initiative/add-epics-to-initiative.md b/docs/api-reference/initiative/add-epics-to-initiative.md index 85aad834..0b83c836 100644 --- a/docs/api-reference/initiative/add-epics-to-initiative.md +++ b/docs/api-reference/initiative/add-epics-to-initiative.md @@ -53,6 +53,14 @@ Array of epic IDs to add to the initiative.
+
+ +### Scopes + +`initiatives.epics:write` + +
+
@@ -63,6 +71,7 @@ Array of epic IDs to add to the initiative. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/epics/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "epic_ids": "example-epic_ids" diff --git a/docs/api-reference/initiative/add-initiative-label.md b/docs/api-reference/initiative/add-initiative-label.md index 8b12dab1..d0b688c4 100644 --- a/docs/api-reference/initiative/add-initiative-label.md +++ b/docs/api-reference/initiative/add-initiative-label.md @@ -65,6 +65,14 @@ Sort order for display purposes.
+
+ +### Scopes + +`initiatives.labels:write` + +
+
@@ -75,6 +83,7 @@ Sort order for display purposes. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/labels/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/initiative/add-initiative.md b/docs/api-reference/initiative/add-initiative.md index 38039a1a..046bc3f1 100644 --- a/docs/api-reference/initiative/add-initiative.md +++ b/docs/api-reference/initiative/add-initiative.md @@ -101,6 +101,14 @@ Current state of the initiative. Possible values: `DRAFT`, `PLANNED`, `ACTIVE`,
+
+ +### Scopes + +`initiatives:write` + +
+
@@ -111,6 +119,7 @@ Current state of the initiative. Possible values: `DRAFT`, `PLANNED`, `ACTIVE`, curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/initiative/add-labels-to-initiative.md b/docs/api-reference/initiative/add-labels-to-initiative.md index 66b65ae8..7a1d4a97 100644 --- a/docs/api-reference/initiative/add-labels-to-initiative.md +++ b/docs/api-reference/initiative/add-labels-to-initiative.md @@ -53,6 +53,14 @@ Array of initiative label IDs to add to the initiative.
+
+ +### Scopes + +`initiatives:write` + +
+
@@ -63,6 +71,7 @@ Array of initiative label IDs to add to the initiative. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/labels/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "label_ids": "example-label_ids" diff --git a/docs/api-reference/initiative/add-projects-to-initiative.md b/docs/api-reference/initiative/add-projects-to-initiative.md index e163fd15..6bd33fb8 100644 --- a/docs/api-reference/initiative/add-projects-to-initiative.md +++ b/docs/api-reference/initiative/add-projects-to-initiative.md @@ -53,6 +53,14 @@ Array of project IDs to add to the initiative.
+
+ +### Scopes + +`initiatives.projects:write` + +
+
@@ -63,6 +71,7 @@ Array of project IDs to add to the initiative. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/projects/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project_ids": "example-project_ids" diff --git a/docs/api-reference/initiative/delete-initiative-label.md b/docs/api-reference/initiative/delete-initiative-label.md index 79743385..bbbfb456 100644 --- a/docs/api-reference/initiative/delete-initiative-label.md +++ b/docs/api-reference/initiative/delete-initiative-label.md @@ -38,6 +38,14 @@ The unique identifier for the initiative label.
+
+ +### Scopes + +`initiatives.labels:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the initiative label. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/labels/label-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/initiative/delete-initiative.md b/docs/api-reference/initiative/delete-initiative.md index c965f2eb..6424909d 100644 --- a/docs/api-reference/initiative/delete-initiative.md +++ b/docs/api-reference/initiative/delete-initiative.md @@ -38,6 +38,14 @@ The unique identifier for the initiative.
+
+ +### Scopes + +`initiatives:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the initiative. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/initiative/get-initiative-detail.md b/docs/api-reference/initiative/get-initiative-detail.md index 4760bb1d..583bdbd9 100644 --- a/docs/api-reference/initiative/get-initiative-detail.md +++ b/docs/api-reference/initiative/get-initiative-detail.md @@ -38,6 +38,14 @@ The unique identifier for the initiative.
+
+ +### Scopes + +`initiatives:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the initiative. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/initiative/get-initiative-label-detail.md b/docs/api-reference/initiative/get-initiative-label-detail.md index fb383635..c0ec7eba 100644 --- a/docs/api-reference/initiative/get-initiative-label-detail.md +++ b/docs/api-reference/initiative/get-initiative-label-detail.md @@ -38,6 +38,14 @@ The unique identifier for the initiative label.
+
+ +### Scopes + +`initiatives.labels:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the initiative label. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/labels/label-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/initiative/list-initiative-epics.md b/docs/api-reference/initiative/list-initiative-epics.md index 1123e1ce..ea8ddaa0 100644 --- a/docs/api-reference/initiative/list-initiative-epics.md +++ b/docs/api-reference/initiative/list-initiative-epics.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`initiatives.epics:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/epics/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/initiative/list-initiative-labels-for-initiative.md b/docs/api-reference/initiative/list-initiative-labels-for-initiative.md index 2a4b2c73..7152f628 100644 --- a/docs/api-reference/initiative/list-initiative-labels-for-initiative.md +++ b/docs/api-reference/initiative/list-initiative-labels-for-initiative.md @@ -4,7 +4,6 @@ description: List all labels for an initiative via Plane API. HTTP GET request w keywords: plane, plane api, rest api, api integration, labels, tags, categorization, initiatives, roadmap, planning --- - # List all labels for an initiative
@@ -59,6 +58,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`initiatives:read` + +
+
@@ -68,7 +75,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/labels/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -93,8 +101,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/initiative/list-initiative-labels.md b/docs/api-reference/initiative/list-initiative-labels.md index fb6c293a..c32209be 100644 --- a/docs/api-reference/initiative/list-initiative-labels.md +++ b/docs/api-reference/initiative/list-initiative-labels.md @@ -4,7 +4,6 @@ description: List all initiative labels via Plane API. HTTP GET request with pag keywords: plane, plane api, rest api, api integration, labels, tags, categorization, initiatives, roadmap, planning --- - # List all initiative labels
@@ -53,6 +52,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`initiatives.labels:read` + +
+
@@ -62,7 +69,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/labels/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -82,15 +90,12 @@ print(response.json()) @@ -93,8 +101,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/initiative/list-initiatives.md b/docs/api-reference/initiative/list-initiatives.md index eac44752..64b2bcff 100644 --- a/docs/api-reference/initiative/list-initiatives.md +++ b/docs/api-reference/initiative/list-initiatives.md @@ -4,7 +4,6 @@ description: List all initiatives via Plane API. HTTP GET request with paginatio keywords: plane, plane api, rest api, api integration, initiatives, roadmap, planning --- - # List all initiatives
@@ -53,6 +52,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`initiatives:read` + +
+
@@ -62,7 +69,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -82,15 +90,12 @@ print(response.json()) @@ -82,15 +90,12 @@ print(response.json()) @@ -87,8 +95,8 @@ const response = await fetch( { method: "DELETE", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/initiative/remove-projects-from-initiative.md b/docs/api-reference/initiative/remove-projects-from-initiative.md index 11f125e9..22a444eb 100644 --- a/docs/api-reference/initiative/remove-projects-from-initiative.md +++ b/docs/api-reference/initiative/remove-projects-from-initiative.md @@ -4,7 +4,6 @@ description: Delete projects from initiative via Plane API. HTTP DELETE request keywords: plane, plane api, rest api, api integration, projects, project management, initiatives, roadmap, planning --- - # Remove projects from initiative
@@ -53,6 +52,14 @@ Array of project IDs to remove from the initiative.
+
+ +### Scopes + +`initiatives.projects:write` + +
+
@@ -62,7 +69,8 @@ Array of project IDs to remove from the initiative. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/projects/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -87,8 +95,8 @@ const response = await fetch( { method: "DELETE", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/initiative/update-initiative-detail.md b/docs/api-reference/initiative/update-initiative-detail.md index db3358d3..e8320c3a 100644 --- a/docs/api-reference/initiative/update-initiative-detail.md +++ b/docs/api-reference/initiative/update-initiative-detail.md @@ -4,7 +4,6 @@ description: Update an initiative via Plane API. HTTP PATCH request format, edit keywords: plane, plane api, rest api, api integration, initiatives, roadmap, planning --- - # Update an initiative
@@ -107,6 +106,14 @@ Current state of the initiative. Possible values: `DRAFT`, `PLANNED`, `ACTIVE`,
+
+ +### Scopes + +`initiatives:write` + +
+
@@ -117,6 +124,7 @@ Current state of the initiative. Possible values: `DRAFT`, `PLANNED`, `ACTIVE`, curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/initiatives/{initiative_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", @@ -161,28 +169,25 @@ print(response.json()) @@ -78,8 +86,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/intake-issue/list-intake-issues.md b/docs/api-reference/intake-issue/list-intake-issues.md index b972fa03..2f579b7f 100644 --- a/docs/api-reference/intake-issue/list-intake-issues.md +++ b/docs/api-reference/intake-issue/list-intake-issues.md @@ -4,7 +4,6 @@ description: List all intake work items via Plane API. HTTP GET request with pag keywords: plane, plane api, rest api, api integration, work items, issues, tasks, intake, triage, submissions --- - # List all intake work items
@@ -38,6 +37,14 @@ The unique identifier of the project
+
+ +### Scopes + +`projects.intakes:read` + +
+
@@ -47,7 +54,8 @@ The unique identifier of the project ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/intake-issues/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -72,8 +80,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/intake-issue/update-intake-issue-detail.md b/docs/api-reference/intake-issue/update-intake-issue-detail.md index 92dc2612..c385332b 100644 --- a/docs/api-reference/intake-issue/update-intake-issue-detail.md +++ b/docs/api-reference/intake-issue/update-intake-issue-detail.md @@ -4,7 +4,6 @@ description: Update an intake work item via Plane API. HTTP PATCH request format keywords: plane, plane api, rest api, api integration, work items, issues, tasks, intake, triage, submissions --- - # Update an intake work item
@@ -59,6 +58,14 @@ An object containing the intake work item details to update, including an option
+
+ +### Scopes + +`projects.intakes:write` + +
+
@@ -69,6 +76,7 @@ An object containing the intake work item details to update, including an option curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/intake-issues/issue-uuid" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issue": "example-issue" @@ -101,11 +109,11 @@ const response = await fetch( method: "PATCH", headers: { "X-API-Key": "your-api-key", - "Content-Type": "application/json" + "Content-Type": "application/json", }, body: JSON.stringify({ - "issue": "example-issue" -}) + issue: "example-issue", + }), } ); const data = await response.json(); diff --git a/docs/api-reference/introduction.md b/docs/api-reference/introduction.md index c0014cf4..673b927b 100644 --- a/docs/api-reference/introduction.md +++ b/docs/api-reference/introduction.md @@ -55,15 +55,32 @@ X-API-Key: It is important to keep your API key confidential to prevent unauthorized access to your account. +### Using an OAuth Token + +If your application uses [OAuth](/dev-tools/build-plane-app/overview) to obtain user authorization (for example, a Plane app you've built), you can authenticate API requests with the OAuth access token. Include the token in the `Authorization` header as a Bearer token: + +``` +Authorization: Bearer +``` + +The access token is scoped to the permissions (scopes) the user granted when authorizing your app. See [OAuth scopes](/dev-tools/build-plane-app/oauth-scopes) for the full list of available scopes. + ### Example of an Authenticated API Request -**Request:** +**Using an API key:** ``` GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/work-items/ Headers: X-API-Key: plane_api_ ``` +**Using an OAuth token:** +``` +GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/work-items/ +Headers: + Authorization: Bearer +``` + **Response:** ```json { diff --git a/docs/api-reference/issue-activity/get-issue-activity-detail.md b/docs/api-reference/issue-activity/get-issue-activity-detail.md index 881ffd90..54779c81 100644 --- a/docs/api-reference/issue-activity/get-issue-activity-detail.md +++ b/docs/api-reference/issue-activity/get-issue-activity-detail.md @@ -4,7 +4,6 @@ description: Get retrieve a work item activity details via Plane API. Retrieve c keywords: plane, plane api, rest api, api integration, work items, issues, tasks --- - # Retrieve a work item activity
@@ -50,6 +49,14 @@ The unique identifier for the activity.
+
+ +### Scopes + +`projects.work_items.activities:read` + +
+
@@ -59,7 +66,8 @@ The unique identifier for the activity. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/activities/{activity_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -84,8 +92,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-activity/list-issue-activities.md b/docs/api-reference/issue-activity/list-issue-activities.md index 2d7c912f..d2f908a4 100644 --- a/docs/api-reference/issue-activity/list-issue-activities.md +++ b/docs/api-reference/issue-activity/list-issue-activities.md @@ -4,7 +4,6 @@ description: List all work item activity via Plane API. HTTP GET request with pa keywords: plane, plane api, rest api, api integration, work items, issues, tasks --- - # List all work item activity
@@ -44,6 +43,14 @@ The unique identifier for the work item.
+
+ +### Scopes + +`projects.work_items.activities:read` + +
+
@@ -53,7 +60,8 @@ The unique identifier for the work item. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/activities/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -78,8 +86,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/complete-upload.md b/docs/api-reference/issue-attachments/complete-upload.md index 0698d690..7bed283b 100644 --- a/docs/api-reference/issue-attachments/complete-upload.md +++ b/docs/api-reference/issue-attachments/complete-upload.md @@ -4,7 +4,6 @@ description: Complete upload API endpoint. Request format, parameters, and respo keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # Complete upload
@@ -50,6 +49,14 @@ The unique identifier of the attachment generated by the [Get upload credentials
+
+ +### Scopes + +`projects.work_items.attachments:write` + +
+
@@ -59,7 +66,8 @@ The unique identifier of the attachment generated by the [Get upload credentials ```bash curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/{asset_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -84,8 +92,8 @@ const response = await fetch( { method: "PATCH", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/delete-attachment.md b/docs/api-reference/issue-attachments/delete-attachment.md index f04c09d4..0481f89d 100644 --- a/docs/api-reference/issue-attachments/delete-attachment.md +++ b/docs/api-reference/issue-attachments/delete-attachment.md @@ -4,7 +4,6 @@ description: Delete an attachment via Plane API. HTTP DELETE request for removin keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # Delete an attachment
@@ -50,6 +49,14 @@ The unique identifier of the attachment.
+
+ +### Scopes + +`projects.work_items.attachments:write` + +
+
@@ -59,7 +66,8 @@ The unique identifier of the attachment. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/{attachment_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -84,8 +92,8 @@ const response = await fetch( { method: "DELETE", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/get-attachment-detail.md b/docs/api-reference/issue-attachments/get-attachment-detail.md index 56231c4e..3a259fb4 100644 --- a/docs/api-reference/issue-attachments/get-attachment-detail.md +++ b/docs/api-reference/issue-attachments/get-attachment-detail.md @@ -4,7 +4,6 @@ description: Get retrieve an attachment details via Plane API. Retrieve complete keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # Retrieve an attachment
@@ -50,7 +49,15 @@ The unique identifier of the attachment
+
+ +### Scopes + +`projects.work_items.attachments:read` + +
+
@@ -59,7 +66,8 @@ The unique identifier of the attachment ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/{attachment_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -84,8 +92,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/get-attachments.md b/docs/api-reference/issue-attachments/get-attachments.md index 32c7e862..f78fc2d5 100644 --- a/docs/api-reference/issue-attachments/get-attachments.md +++ b/docs/api-reference/issue-attachments/get-attachments.md @@ -4,7 +4,6 @@ description: List all attachments via Plane API. HTTP GET request with paginatio keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # List all attachments
@@ -83,6 +82,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`projects.work_items.attachments:read` + +
+
@@ -92,7 +99,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -117,8 +125,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/get-upload-credentials.md b/docs/api-reference/issue-attachments/get-upload-credentials.md index 9ceed0d7..be83acbc 100644 --- a/docs/api-reference/issue-attachments/get-upload-credentials.md +++ b/docs/api-reference/issue-attachments/get-upload-credentials.md @@ -4,7 +4,6 @@ description: List upload credentials via Plane API. HTTP GET request with pagina keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # Get upload credentials
@@ -83,6 +82,14 @@ External source system (for integration tracking).
+
+ +### Scopes + +`projects.work_items.attachments:write` + +
+
@@ -93,6 +100,7 @@ External source system (for integration tracking). curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", @@ -133,15 +141,15 @@ const response = await fetch( method: "POST", headers: { "X-API-Key": "your-api-key", - "Content-Type": "application/json" + "Content-Type": "application/json", }, body: JSON.stringify({ - "name": "example-name", - "type": "example-type", - "size": 1, - "external_id": "example-external_id", - "external_source": "example-external_source" -}) + name: "example-name", + type: "example-type", + size: 1, + external_id: "example-external_id", + external_source: "example-external_source", + }), } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/update-attachment.md b/docs/api-reference/issue-attachments/update-attachment.md index 9626328c..86632c85 100644 --- a/docs/api-reference/issue-attachments/update-attachment.md +++ b/docs/api-reference/issue-attachments/update-attachment.md @@ -4,7 +4,6 @@ description: Update an attachment via Plane API. HTTP PATCH request format, edit keywords: plane, plane api, rest api, api integration, work items, issues, tasks, attachments, files, uploads --- - # Update an attachment
@@ -125,6 +124,14 @@ Cloud storage metadata.
+
+ +### Scopes + +`projects.work_items.attachments:write` + +
+
@@ -135,6 +142,7 @@ Cloud storage metadata. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/attachments/{attachment_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "attributes": "example-attributes", @@ -187,21 +195,21 @@ const response = await fetch( method: "PATCH", headers: { "X-API-Key": "your-api-key", - "Content-Type": "application/json" + "Content-Type": "application/json", }, body: JSON.stringify({ - "attributes": "example-attributes", - "asset": "example-asset", - "entity_type": "example-entity_type", - "entity_identifier": "example-entity_identifier", - "is_deleted": true, - "is_archived": true, - "external_id": "example-external_id", - "external_source": "example-external_source", - "size": 1, - "is_uploaded": true, - "storage_metadata": "example-storage_metadata" -}) + attributes: "example-attributes", + asset: "example-asset", + entity_type: "example-entity_type", + entity_identifier: "example-entity_identifier", + is_deleted: true, + is_archived: true, + external_id: "example-external_id", + external_source: "example-external_source", + size: 1, + is_uploaded: true, + storage_metadata: "example-storage_metadata", + }), } ); const data = await response.json(); diff --git a/docs/api-reference/issue-attachments/upload-file.md b/docs/api-reference/issue-attachments/upload-file.md index a85ffb5b..d8555d73 100644 --- a/docs/api-reference/issue-attachments/upload-file.md +++ b/docs/api-reference/issue-attachments/upload-file.md @@ -82,8 +82,9 @@ The file to be uploaded ```bash curl -X POST \ - "https://api.plane.sohttps://planefs-uploads.s3.amazonaws.com/" \ + "https://planefs-uploads.s3.amazonaws.com/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Content-Type": "example-Content-Type", diff --git a/docs/api-reference/issue-comment/add-issue-comment.md b/docs/api-reference/issue-comment/add-issue-comment.md index 85463e78..6c81c79e 100644 --- a/docs/api-reference/issue-comment/add-issue-comment.md +++ b/docs/api-reference/issue-comment/add-issue-comment.md @@ -83,6 +83,14 @@ ID from the external source.
+
+ +### Scopes + +`projects.work_items.comments:write` + +
+
@@ -93,6 +101,7 @@ ID from the external source. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/comments/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "comment_html": "example-comment_html", diff --git a/docs/api-reference/issue-comment/delete-issue-comment.md b/docs/api-reference/issue-comment/delete-issue-comment.md index 833ae416..50b8d12b 100644 --- a/docs/api-reference/issue-comment/delete-issue-comment.md +++ b/docs/api-reference/issue-comment/delete-issue-comment.md @@ -50,6 +50,14 @@ The unique identifier for the comment.
+
+ +### Scopes + +`projects.work_items.comments:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the comment. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/comments/comment-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-comment/get-issue-comment-detail.md b/docs/api-reference/issue-comment/get-issue-comment-detail.md index 016e13cb..b432c87f 100644 --- a/docs/api-reference/issue-comment/get-issue-comment-detail.md +++ b/docs/api-reference/issue-comment/get-issue-comment-detail.md @@ -50,6 +50,14 @@ The unique identifier for the comment.
+
+ +### Scopes + +`projects.work_items.comments:read` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the comment. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/comments/comment-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-comment/list-issue-comments.md b/docs/api-reference/issue-comment/list-issue-comments.md index 827bdaea..b0006fda 100644 --- a/docs/api-reference/issue-comment/list-issue-comments.md +++ b/docs/api-reference/issue-comment/list-issue-comments.md @@ -83,6 +83,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`projects.work_items.comments:read` + +
+
@@ -92,7 +100,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/comments/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-comment/update-issue-comment-detail.md b/docs/api-reference/issue-comment/update-issue-comment-detail.md index 7d52e01b..8bc9d025 100644 --- a/docs/api-reference/issue-comment/update-issue-comment-detail.md +++ b/docs/api-reference/issue-comment/update-issue-comment-detail.md @@ -89,6 +89,14 @@ ID from the external source.
+
+ +### Scopes + +`projects.work_items.comments:write` + +
+
@@ -99,6 +107,7 @@ ID from the external source. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/comments/comment-uuid/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "comment_html": "example-comment_html", diff --git a/docs/api-reference/issue-types/options/add-dropdown-options.md b/docs/api-reference/issue-types/options/add-dropdown-options.md index 2e64d62f..7bf91095 100644 --- a/docs/api-reference/issue-types/options/add-dropdown-options.md +++ b/docs/api-reference/issue-types/options/add-dropdown-options.md @@ -83,6 +83,14 @@ Whether this option is currently active.
+
+ +### Scopes + +`projects.work_item_property_options:write` + +
+
@@ -93,6 +101,7 @@ Whether this option is currently active. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-properties/{property_id}/options/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/issue-types/options/delete-dropdown-options.md b/docs/api-reference/issue-types/options/delete-dropdown-options.md index 669818a4..8c53dd6d 100644 --- a/docs/api-reference/issue-types/options/delete-dropdown-options.md +++ b/docs/api-reference/issue-types/options/delete-dropdown-options.md @@ -50,6 +50,14 @@ The unique identifier for the option.
+
+ +### Scopes + +`projects.work_item_property_options:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the option. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-properties/{property_id}/options/{option_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/options/get-option-details.md b/docs/api-reference/issue-types/options/get-option-details.md index 196b5ff8..539dbd12 100644 --- a/docs/api-reference/issue-types/options/get-option-details.md +++ b/docs/api-reference/issue-types/options/get-option-details.md @@ -50,6 +50,14 @@ The unique identifier for the option.
+
+ +### Scopes + +`projects.work_item_property_options:read` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the option. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-properties/{property_id}/options/{option_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/options/list-dropdown-options.md b/docs/api-reference/issue-types/options/list-dropdown-options.md index d9d5d0a9..aeec4cb2 100644 --- a/docs/api-reference/issue-types/options/list-dropdown-options.md +++ b/docs/api-reference/issue-types/options/list-dropdown-options.md @@ -44,6 +44,14 @@ The unique identifier for the custom property.
+
+ +### Scopes + +`projects.work_item_property_options:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the custom property. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-properties/{property_id}/options/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/options/update-dropdown-options.md b/docs/api-reference/issue-types/options/update-dropdown-options.md index 9a3b08e0..b3e3b2a6 100644 --- a/docs/api-reference/issue-types/options/update-dropdown-options.md +++ b/docs/api-reference/issue-types/options/update-dropdown-options.md @@ -89,6 +89,14 @@ Whether this option is currently active.
+
+ +### Scopes + +`projects.work_item_property_options:write` + +
+
@@ -99,6 +107,7 @@ Whether this option is currently active. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-properties/{property_id}/options/{option_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/issue-types/properties/add-property.md b/docs/api-reference/issue-types/properties/add-property.md index 6711a38b..b4d6c08a 100644 --- a/docs/api-reference/issue-types/properties/add-property.md +++ b/docs/api-reference/issue-types/properties/add-property.md @@ -110,6 +110,14 @@ To add or update options on an OPTION property after creation, you can use the A
+
+ +### Scopes + +`projects.work_item_properties:write` + +
+
@@ -120,6 +128,7 @@ To add or update options on an OPTION property after creation, you can use the A curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/work-item-properties/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "display_name": "example-display_name", diff --git a/docs/api-reference/issue-types/properties/delete-property.md b/docs/api-reference/issue-types/properties/delete-property.md index 56bd1180..f44b714a 100644 --- a/docs/api-reference/issue-types/properties/delete-property.md +++ b/docs/api-reference/issue-types/properties/delete-property.md @@ -50,6 +50,14 @@ The unique identifier for the custom property.
+
+ +### Scopes + +`projects.work_item_properties:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the custom property. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/work-item-properties/{property_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/properties/get-property-details.md b/docs/api-reference/issue-types/properties/get-property-details.md index 653707df..968608a7 100644 --- a/docs/api-reference/issue-types/properties/get-property-details.md +++ b/docs/api-reference/issue-types/properties/get-property-details.md @@ -50,6 +50,14 @@ The unique identifier for the custom property.
+
+ +### Scopes + +`projects.work_item_properties:read` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the custom property. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/work-item-properties/{property_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/properties/list-properties.md b/docs/api-reference/issue-types/properties/list-properties.md index 4bb88333..709bbb1c 100644 --- a/docs/api-reference/issue-types/properties/list-properties.md +++ b/docs/api-reference/issue-types/properties/list-properties.md @@ -44,6 +44,14 @@ The unique identifier for the work item type.
+
+ +### Scopes + +`projects.work_item_properties:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the work item type. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/work-item-properties/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/properties/update-property.md b/docs/api-reference/issue-types/properties/update-property.md index 6ee1117b..5795003e 100644 --- a/docs/api-reference/issue-types/properties/update-property.md +++ b/docs/api-reference/issue-types/properties/update-property.md @@ -101,6 +101,14 @@ Whether this property allows multiple values.
+
+ +### Scopes + +`projects.work_item_properties:write` + +
+
@@ -111,6 +119,7 @@ Whether this property allows multiple values. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/work-item-properties/{property_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "display_name": "example-display_name", diff --git a/docs/api-reference/issue-types/types/add-issue-type.md b/docs/api-reference/issue-types/types/add-issue-type.md index 35d1a672..4fd5b41f 100644 --- a/docs/api-reference/issue-types/types/add-issue-type.md +++ b/docs/api-reference/issue-types/types/add-issue-type.md @@ -89,6 +89,14 @@ Hierarchical level of the work item type.
+
+ +### Scopes + +`projects.work_item_types:write` + +
+
@@ -99,6 +107,7 @@ Hierarchical level of the work item type. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/issue-types/types/delete-issue-type.md b/docs/api-reference/issue-types/types/delete-issue-type.md index ff10aa06..f2125e64 100644 --- a/docs/api-reference/issue-types/types/delete-issue-type.md +++ b/docs/api-reference/issue-types/types/delete-issue-type.md @@ -44,6 +44,14 @@ The unique identifier for the work item type.
+
+ +### Scopes + +`projects.work_item_types:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the work item type. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/types/get-issue-type-details.md b/docs/api-reference/issue-types/types/get-issue-type-details.md index dd0aad7f..23573edd 100644 --- a/docs/api-reference/issue-types/types/get-issue-type-details.md +++ b/docs/api-reference/issue-types/types/get-issue-type-details.md @@ -44,6 +44,14 @@ The unique identifier for the work item type.
+
+ +### Scopes + +`projects.work_item_types:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the work item type. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/types/list-issue-types.md b/docs/api-reference/issue-types/types/list-issue-types.md index a1882490..5175eb10 100644 --- a/docs/api-reference/issue-types/types/list-issue-types.md +++ b/docs/api-reference/issue-types/types/list-issue-types.md @@ -65,6 +65,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`projects.work_item_types:read` + +
+
@@ -74,7 +82,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue-types/types/update-issue-types.md b/docs/api-reference/issue-types/types/update-issue-types.md index 9904b39b..3944684f 100644 --- a/docs/api-reference/issue-types/types/update-issue-types.md +++ b/docs/api-reference/issue-types/types/update-issue-types.md @@ -95,6 +95,14 @@ Hierarchical level of the work item type.
+
+ +### Scopes + +`projects.work_item_types:write` + +
+
@@ -105,6 +113,7 @@ Hierarchical level of the work item type. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-item-types/{type_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/issue-types/values/add-property-values.md b/docs/api-reference/issue-types/values/add-property-values.md index 6865b523..382861d1 100644 --- a/docs/api-reference/issue-types/values/add-property-values.md +++ b/docs/api-reference/issue-types/values/add-property-values.md @@ -79,6 +79,14 @@ For single-value properties:
+
+ +### Scopes + +`projects.work_item_property_values:write` + +
+
@@ -89,6 +97,7 @@ For single-value properties: curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/work-item-properties/{property_id}/values/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "value": "example-value" diff --git a/docs/api-reference/issue-types/values/list-property-values.md b/docs/api-reference/issue-types/values/list-property-values.md index ae8201f1..5532acf4 100644 --- a/docs/api-reference/issue-types/values/list-property-values.md +++ b/docs/api-reference/issue-types/values/list-property-values.md @@ -50,6 +50,14 @@ The unique identifier for the custom property.
+
+ +### Scopes + +`projects.work_item_property_values:read` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the custom property. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/work-item-properties/{property_id}/values/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/issue/add-issue.md b/docs/api-reference/issue/add-issue.md index 822a8877..b870af81 100644 --- a/docs/api-reference/issue/add-issue.md +++ b/docs/api-reference/issue/add-issue.md @@ -4,7 +4,6 @@ description: Create a work item via Plane API. HTTP POST request format, require keywords: plane, plane api, rest api, api integration, work items, issues, tasks --- - # Create a work item
@@ -119,6 +118,14 @@ Target completion date in YYYY-MM-DD format.
+
+ +### Scopes + +`projects.work_items:write` + +
+
@@ -129,6 +136,7 @@ Target completion date in YYYY-MM-DD format. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", @@ -177,30 +185,27 @@ print(response.json()) @@ -78,8 +86,8 @@ const response = await fetch( { method: "DELETE", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue/get-issue-detail.md b/docs/api-reference/issue/get-issue-detail.md index 7ee86a32..92b24ac8 100644 --- a/docs/api-reference/issue/get-issue-detail.md +++ b/docs/api-reference/issue/get-issue-detail.md @@ -4,7 +4,6 @@ description: Get retrieve a work item by id details via Plane API. Retrieve comp keywords: plane, plane api, rest api, api integration, work items, issues, tasks --- - # Retrieve a work item by ID
@@ -59,6 +58,14 @@ Comma-separated list of fields to expand. Possible values: `type`, `module`, `la
+
+ +### Scopes + +`projects.work_items:read` + +
+
@@ -68,7 +75,8 @@ Comma-separated list of fields to expand. Possible values: `type`, `module`, `la ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -93,8 +101,8 @@ const response = await fetch( { method: "GET", headers: { - "X-API-Key": "your-api-key" - } + "X-API-Key": "your-api-key", + }, } ); const data = await response.json(); diff --git a/docs/api-reference/issue/get-issue-sequence-id.md b/docs/api-reference/issue/get-issue-sequence-id.md index 7bcd14fd..7b7a1522 100644 --- a/docs/api-reference/issue/get-issue-sequence-id.md +++ b/docs/api-reference/issue/get-issue-sequence-id.md @@ -4,7 +4,6 @@ description: List retrieve a work item by identifier via Plane API. HTTP GET req keywords: plane, plane api, rest api, api integration, work items, issues, tasks --- - # Retrieve a work item by identifier
@@ -53,6 +52,14 @@ Comma-separated list of fields to expand. Possible values: `type`, `module`, `la
+
+ +### Scopes + +`projects.work_items:read` + +
+
@@ -62,7 +69,8 @@ Comma-separated list of fields to expand. Possible values: `type`, `module`, `la ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/work-items/{identifier}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` @@ -82,15 +90,12 @@ print(response.json()) @@ -112,15 +120,12 @@ print(response.json()) @@ -82,15 +90,12 @@ print(response.json()) diff --git a/docs/api-reference/label/get-label-detail.md b/docs/api-reference/label/get-label-detail.md index c8dca83a..b7080651 100644 --- a/docs/api-reference/label/get-label-detail.md +++ b/docs/api-reference/label/get-label-detail.md @@ -44,6 +44,14 @@ The unique identifier for the label.
+
+ +### Scopes + +`projects.labels:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the label. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/labels/label-uuid" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/label/list-labels.md b/docs/api-reference/label/list-labels.md index c6f456ee..cfade4f5 100644 --- a/docs/api-reference/label/list-labels.md +++ b/docs/api-reference/label/list-labels.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.labels:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/labels/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/label/update-label-detail.md b/docs/api-reference/label/update-label-detail.md index 35247eb1..ba693c16 100644 --- a/docs/api-reference/label/update-label-detail.md +++ b/docs/api-reference/label/update-label-detail.md @@ -59,6 +59,14 @@ Name of the label.
+
+ +### Scopes + +`projects.labels:write` + +
+
@@ -69,6 +77,7 @@ Name of the label. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/labels/label-uuid" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name" diff --git a/docs/api-reference/link/add-link.md b/docs/api-reference/link/add-link.md index dc60bd0d..a8c7c30f 100644 --- a/docs/api-reference/link/add-link.md +++ b/docs/api-reference/link/add-link.md @@ -65,6 +65,14 @@ URL of the external resource.
+
+ +### Scopes + +`projects.work_items.links:write` + +
+
@@ -75,6 +83,7 @@ URL of the external resource. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/links/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "example-title", diff --git a/docs/api-reference/link/delete-link.md b/docs/api-reference/link/delete-link.md index 91305d88..cb551f6f 100644 --- a/docs/api-reference/link/delete-link.md +++ b/docs/api-reference/link/delete-link.md @@ -50,6 +50,14 @@ The unique identifier for the link.
+
+ +### Scopes + +`projects.work_items.links:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the link. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/links/{link_id}" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/link/get-link-detail.md b/docs/api-reference/link/get-link-detail.md index 248b46e2..fc953e31 100644 --- a/docs/api-reference/link/get-link-detail.md +++ b/docs/api-reference/link/get-link-detail.md @@ -50,6 +50,14 @@ The unique identifier for the link.
+
+ +### Scopes + +`projects.work_items.links:read` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the link. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/links/{link_id}" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/link/list-links.md b/docs/api-reference/link/list-links.md index 6242f934..f856c12b 100644 --- a/docs/api-reference/link/list-links.md +++ b/docs/api-reference/link/list-links.md @@ -44,6 +44,14 @@ The unique identifier for the work item.
+
+ +### Scopes + +`projects.work_items.links:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the work item. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/links/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/link/update-link-detail.md b/docs/api-reference/link/update-link-detail.md index 3af51bc7..babf9926 100644 --- a/docs/api-reference/link/update-link-detail.md +++ b/docs/api-reference/link/update-link-detail.md @@ -71,6 +71,14 @@ URL of the external resource.
+
+ +### Scopes + +`projects.work_items.links:write` + +
+
@@ -81,6 +89,7 @@ URL of the external resource. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/links/{link_id}" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/members/get-project-members.md b/docs/api-reference/members/get-project-members.md index 06137cf3..67e53fd1 100644 --- a/docs/api-reference/members/get-project-members.md +++ b/docs/api-reference/members/get-project-members.md @@ -38,6 +38,14 @@ The unique identifier of the project
+
+ +### Scopes + +`projects.members:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/members/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/members/get-workspace-members.md b/docs/api-reference/members/get-workspace-members.md index fb21be6d..93031e8e 100644 --- a/docs/api-reference/members/get-workspace-members.md +++ b/docs/api-reference/members/get-workspace-members.md @@ -32,6 +32,14 @@ The workspace_slug represents the unique workspace identifier for a workspace in
+
+ +### Scopes + +`workspaces.members:read` + +
+
@@ -41,7 +49,8 @@ The workspace_slug represents the unique workspace identifier for a workspace in ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/members/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/add-module-work-items.md b/docs/api-reference/module/add-module-work-items.md index d87e2905..7852490d 100644 --- a/docs/api-reference/module/add-module-work-items.md +++ b/docs/api-reference/module/add-module-work-items.md @@ -59,6 +59,14 @@ Array of work item IDs to add to the module.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -69,6 +77,7 @@ Array of work item IDs to add to the module. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/module-issues/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "issues": "example-issues" diff --git a/docs/api-reference/module/add-module.md b/docs/api-reference/module/add-module.md index bf20a37d..056d0bc5 100644 --- a/docs/api-reference/module/add-module.md +++ b/docs/api-reference/module/add-module.md @@ -101,6 +101,14 @@ External ID from the external source.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -111,6 +119,7 @@ External ID from the external source. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/module/archive-module.md b/docs/api-reference/module/archive-module.md index 1ae5c2f6..0bd5d83a 100644 --- a/docs/api-reference/module/archive-module.md +++ b/docs/api-reference/module/archive-module.md @@ -44,6 +44,14 @@ The unique identifier for the module.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the module. ```bash curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/archive/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/delete-module.md b/docs/api-reference/module/delete-module.md index 43c440e4..d91d8023 100644 --- a/docs/api-reference/module/delete-module.md +++ b/docs/api-reference/module/delete-module.md @@ -44,6 +44,14 @@ The unique identifier for the module.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the module. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/get-module-detail.md b/docs/api-reference/module/get-module-detail.md index 91ab229c..d22cbc03 100644 --- a/docs/api-reference/module/get-module-detail.md +++ b/docs/api-reference/module/get-module-detail.md @@ -44,6 +44,14 @@ The unique identifier for the module.
+
+ +### Scopes + +`projects.modules:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the module. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/list-archived-modules.md b/docs/api-reference/module/list-archived-modules.md index 02714682..996fff73 100644 --- a/docs/api-reference/module/list-archived-modules.md +++ b/docs/api-reference/module/list-archived-modules.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.modules:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/archived/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/list-module-work-items.md b/docs/api-reference/module/list-module-work-items.md index ffd371bf..3f44168e 100644 --- a/docs/api-reference/module/list-module-work-items.md +++ b/docs/api-reference/module/list-module-work-items.md @@ -44,6 +44,14 @@ The unique identifier for the module.
+
+ +### Scopes + +`projects.modules:read` `projects.work_items:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the module. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/module-issues/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/list-modules.md b/docs/api-reference/module/list-modules.md index 3c6d4de9..5dae29b6 100644 --- a/docs/api-reference/module/list-modules.md +++ b/docs/api-reference/module/list-modules.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.modules:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/remove-module-work-item.md b/docs/api-reference/module/remove-module-work-item.md index f78ebc9f..60a56f16 100644 --- a/docs/api-reference/module/remove-module-work-item.md +++ b/docs/api-reference/module/remove-module-work-item.md @@ -50,6 +50,14 @@ The unique identifier for the work item.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier for the work item. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/module-issues/issue-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/unarchive-module.md b/docs/api-reference/module/unarchive-module.md index ce7566b0..98be7b65 100644 --- a/docs/api-reference/module/unarchive-module.md +++ b/docs/api-reference/module/unarchive-module.md @@ -44,6 +44,14 @@ The unique identifier for the module.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the module. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/unarchive/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/module/update-module-detail.md b/docs/api-reference/module/update-module-detail.md index 4cb3d318..62c93aee 100644 --- a/docs/api-reference/module/update-module-detail.md +++ b/docs/api-reference/module/update-module-detail.md @@ -107,6 +107,14 @@ External ID from the external source.
+
+ +### Scopes + +`projects.modules:write` + +
+
@@ -117,6 +125,7 @@ External ID from the external source. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/modules/module-uuid/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/page/add-project-page.md b/docs/api-reference/page/add-project-page.md index 9b074881..a2ff5b50 100644 --- a/docs/api-reference/page/add-project-page.md +++ b/docs/api-reference/page/add-project-page.md @@ -59,6 +59,14 @@ HTML-formatted content of the page.
+
+ +### Scopes + +`projects.pages:write` + +
+
@@ -69,6 +77,7 @@ HTML-formatted content of the page. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/pages/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/page/add-workspace-page.md b/docs/api-reference/page/add-workspace-page.md index 953d4255..7947e278 100644 --- a/docs/api-reference/page/add-workspace-page.md +++ b/docs/api-reference/page/add-workspace-page.md @@ -53,6 +53,14 @@ HTML-formatted content of the page.
+
+ +### Scopes + +`wiki.pages:write` + +
+
@@ -63,6 +71,7 @@ HTML-formatted content of the page. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/pages/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/page/get-project-page.md b/docs/api-reference/page/get-project-page.md index c2652430..6c7f0c46 100644 --- a/docs/api-reference/page/get-project-page.md +++ b/docs/api-reference/page/get-project-page.md @@ -44,6 +44,14 @@ The unique identifier for the page.
+
+ +### Scopes + +`projects.pages:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the page. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/pages/page-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/page/get-workspace-page.md b/docs/api-reference/page/get-workspace-page.md index 6d08c380..218aab48 100644 --- a/docs/api-reference/page/get-workspace-page.md +++ b/docs/api-reference/page/get-workspace-page.md @@ -38,6 +38,14 @@ The unique identifier for the page.
+
+ +### Scopes + +`wiki.pages:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the page. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/pages/page-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/project/add-project.md b/docs/api-reference/project/add-project.md index ebf0ec2d..a05430fd 100644 --- a/docs/api-reference/project/add-project.md +++ b/docs/api-reference/project/add-project.md @@ -59,7 +59,16 @@ Description of the project.
+
+ +### Scopes + +`projects:write` +
+ + +
@@ -69,6 +78,7 @@ Description of the project. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", @@ -135,4 +145,5 @@ const data = await response.json();
+ diff --git a/docs/api-reference/project/delete-project.md b/docs/api-reference/project/delete-project.md index c89d5eaf..f990fb38 100644 --- a/docs/api-reference/project/delete-project.md +++ b/docs/api-reference/project/delete-project.md @@ -38,6 +38,14 @@ The unique identifier of the project +
+ +### Scopes + +`projects:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/project/get-project-detail.md b/docs/api-reference/project/get-project-detail.md index 708135ff..4a589cf8 100644 --- a/docs/api-reference/project/get-project-detail.md +++ b/docs/api-reference/project/get-project-detail.md @@ -38,6 +38,14 @@ The unique identifier of the project
+
+ +### Scopes + +`projects:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/project/list-projects.md b/docs/api-reference/project/list-projects.md index 795fe7a1..7fb64294 100644 --- a/docs/api-reference/project/list-projects.md +++ b/docs/api-reference/project/list-projects.md @@ -32,6 +32,14 @@ The workspace_slug represents the unique workspace identifier for a workspace in
+
+ +### Scopes + +`projects:read` + +
+
@@ -42,6 +50,7 @@ The workspace_slug represents the unique workspace identifier for a workspace in curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/project/update-project-detail.md b/docs/api-reference/project/update-project-detail.md index a9a21a89..cb4793aa 100644 --- a/docs/api-reference/project/update-project-detail.md +++ b/docs/api-reference/project/update-project-detail.md @@ -59,6 +59,14 @@ Description of the project.
+
+ +### Scopes + +`projects:write` + +
+
@@ -69,6 +77,7 @@ Description of the project. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/state/add-state.md b/docs/api-reference/state/add-state.md index f74c2ee3..b86f1042 100644 --- a/docs/api-reference/state/add-state.md +++ b/docs/api-reference/state/add-state.md @@ -59,6 +59,14 @@ Hex color code for the state (e.g., "#eb5757").
+
+ +### Scopes + +`projects.states:write` + +
+
@@ -69,6 +77,7 @@ Hex color code for the state (e.g., "#eb5757"). curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/states/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/state/delete-state.md b/docs/api-reference/state/delete-state.md index b3ede0e0..68647096 100644 --- a/docs/api-reference/state/delete-state.md +++ b/docs/api-reference/state/delete-state.md @@ -44,6 +44,14 @@ The unique identifier for the state.
+
+ +### Scopes + +`projects.states:write` + +
+
@@ -54,6 +62,7 @@ The unique identifier for the state. curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/states/state-uuid/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/state/get-state-detail.md b/docs/api-reference/state/get-state-detail.md index ec084e85..e92be348 100644 --- a/docs/api-reference/state/get-state-detail.md +++ b/docs/api-reference/state/get-state-detail.md @@ -44,6 +44,14 @@ The unique identifier for the state.
+
+ +### Scopes + +`projects.states:read` + +
+
@@ -53,7 +61,8 @@ The unique identifier for the state. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/states/state-uuid/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/state/list-states.md b/docs/api-reference/state/list-states.md index 820f2a1b..0f05a282 100644 --- a/docs/api-reference/state/list-states.md +++ b/docs/api-reference/state/list-states.md @@ -38,6 +38,14 @@ The unique identifier of the project.
+
+ +### Scopes + +`projects.states:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier of the project. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/states/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/state/update-state-detail.md b/docs/api-reference/state/update-state-detail.md index e4c675b7..5d09d864 100644 --- a/docs/api-reference/state/update-state-detail.md +++ b/docs/api-reference/state/update-state-detail.md @@ -59,6 +59,14 @@ Name of the state.
+
+ +### Scopes + +`projects.states:write` + +
+
@@ -69,6 +77,7 @@ Name of the state. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/states/state-uuid/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name" diff --git a/docs/api-reference/sticky/add-sticky.md b/docs/api-reference/sticky/add-sticky.md index 1be12425..f2bd222b 100644 --- a/docs/api-reference/sticky/add-sticky.md +++ b/docs/api-reference/sticky/add-sticky.md @@ -71,6 +71,14 @@ Background color for the sticky (hex code).
+
+ +### Scopes + +`stickies:write` + +
+
@@ -81,6 +89,7 @@ Background color for the sticky (hex code). curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/stickies/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/sticky/delete-sticky.md b/docs/api-reference/sticky/delete-sticky.md index 299b34fc..bba0e5c4 100644 --- a/docs/api-reference/sticky/delete-sticky.md +++ b/docs/api-reference/sticky/delete-sticky.md @@ -38,6 +38,14 @@ The unique identifier for the sticky.
+
+ +### Scopes + +`stickies:write` + +
+
@@ -47,7 +55,8 @@ The unique identifier for the sticky. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/stickies/{sticky_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/sticky/get-sticky-detail.md b/docs/api-reference/sticky/get-sticky-detail.md index be31c30c..90e11dbe 100644 --- a/docs/api-reference/sticky/get-sticky-detail.md +++ b/docs/api-reference/sticky/get-sticky-detail.md @@ -38,6 +38,14 @@ The unique identifier for the sticky.
+
+ +### Scopes + +`stickies:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the sticky. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/stickies/{sticky_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/sticky/list-stickies.md b/docs/api-reference/sticky/list-stickies.md index fcfddbb8..1029d7c4 100644 --- a/docs/api-reference/sticky/list-stickies.md +++ b/docs/api-reference/sticky/list-stickies.md @@ -53,6 +53,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`stickies:read` + +
+
@@ -63,6 +71,7 @@ Number of results to skip for pagination. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/stickies/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/sticky/update-sticky-detail.md b/docs/api-reference/sticky/update-sticky-detail.md index e09e839c..e65ba6cf 100644 --- a/docs/api-reference/sticky/update-sticky-detail.md +++ b/docs/api-reference/sticky/update-sticky-detail.md @@ -77,6 +77,14 @@ Background color for the sticky (hex code).
+
+ +### Scopes + +`stickies:write` + +
+
@@ -87,6 +95,7 @@ Background color for the sticky (hex code). curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/stickies/{sticky_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/teamspace/add-projects-to-teamspace.md b/docs/api-reference/teamspace/add-projects-to-teamspace.md index a9c511e5..a6940e50 100644 --- a/docs/api-reference/teamspace/add-projects-to-teamspace.md +++ b/docs/api-reference/teamspace/add-projects-to-teamspace.md @@ -53,6 +53,14 @@ Array of project IDs to add to the teamspace
+
+ +### Scopes + +`teamspaces.projects:write` + +
+
@@ -63,6 +71,7 @@ Array of project IDs to add to the teamspace curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/projects/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project_ids": "example-project_ids" diff --git a/docs/api-reference/teamspace/add-teamspace-members.md b/docs/api-reference/teamspace/add-teamspace-members.md index 96c97b3d..cecc8e60 100644 --- a/docs/api-reference/teamspace/add-teamspace-members.md +++ b/docs/api-reference/teamspace/add-teamspace-members.md @@ -53,6 +53,14 @@ Array of user IDs to add to the teamspace.
+
+ +### Scopes + +`teamspaces.members:write` + +
+
@@ -63,6 +71,7 @@ Array of user IDs to add to the teamspace. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/members/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "member_ids": "example-member_ids" diff --git a/docs/api-reference/teamspace/add-teamspace.md b/docs/api-reference/teamspace/add-teamspace.md index bc1f8b5a..d1de0f7b 100644 --- a/docs/api-reference/teamspace/add-teamspace.md +++ b/docs/api-reference/teamspace/add-teamspace.md @@ -83,6 +83,14 @@ ID of the user who leads the teamspace.
+
+ +### Scopes + +`teamspaces:write` + +
+
@@ -93,6 +101,7 @@ ID of the user who leads the teamspace. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/teamspace/delete-teamspace.md b/docs/api-reference/teamspace/delete-teamspace.md index c7de15cd..d0ab958e 100644 --- a/docs/api-reference/teamspace/delete-teamspace.md +++ b/docs/api-reference/teamspace/delete-teamspace.md @@ -38,6 +38,14 @@ The unique identifier for the teamspace.
+
+ +### Scopes + +`teamspaces:write` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the teamspace. curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/get-teamspace-detail.md b/docs/api-reference/teamspace/get-teamspace-detail.md index 5085d6ea..74b54650 100644 --- a/docs/api-reference/teamspace/get-teamspace-detail.md +++ b/docs/api-reference/teamspace/get-teamspace-detail.md @@ -38,6 +38,14 @@ The unique identifier for the teamspace.
+
+ +### Scopes + +`teamspaces:read` + +
+
@@ -48,6 +56,7 @@ The unique identifier for the teamspace. curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/list-teamspace-members.md b/docs/api-reference/teamspace/list-teamspace-members.md index 164a3835..c9d3bb19 100644 --- a/docs/api-reference/teamspace/list-teamspace-members.md +++ b/docs/api-reference/teamspace/list-teamspace-members.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`teamspaces.members:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/members/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/list-teamspace-projects.md b/docs/api-reference/teamspace/list-teamspace-projects.md index 4b393304..e5660293 100644 --- a/docs/api-reference/teamspace/list-teamspace-projects.md +++ b/docs/api-reference/teamspace/list-teamspace-projects.md @@ -59,6 +59,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`teamspaces.projects:read` + +
+
@@ -68,7 +76,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/projects/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/list-teamspaces.md b/docs/api-reference/teamspace/list-teamspaces.md index 95d59383..79cbff6c 100644 --- a/docs/api-reference/teamspace/list-teamspaces.md +++ b/docs/api-reference/teamspace/list-teamspaces.md @@ -53,6 +53,14 @@ Number of results to skip for pagination.
+
+ +### Scopes + +`teamspaces:read` + +
+
@@ -62,7 +70,8 @@ Number of results to skip for pagination. ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/remove-projects-from-teamspace.md b/docs/api-reference/teamspace/remove-projects-from-teamspace.md index 812a7492..2cdbae8f 100644 --- a/docs/api-reference/teamspace/remove-projects-from-teamspace.md +++ b/docs/api-reference/teamspace/remove-projects-from-teamspace.md @@ -53,6 +53,14 @@ Array of project IDs to remove from the teamspace.
+
+ +### Scopes + +`teamspaces.projects:write` + +
+
@@ -62,7 +70,8 @@ Array of project IDs to remove from the teamspace. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/projects/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/remove-teamspace-members.md b/docs/api-reference/teamspace/remove-teamspace-members.md index 9d19b8aa..73b6df98 100644 --- a/docs/api-reference/teamspace/remove-teamspace-members.md +++ b/docs/api-reference/teamspace/remove-teamspace-members.md @@ -53,6 +53,14 @@ Array of user IDs to remove from the teamspace.
+
+ +### Scopes + +`teamspaces.members:write` + +
+
@@ -62,7 +70,8 @@ Array of user IDs to remove from the teamspace. ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/members/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/teamspace/update-teamspace-detail.md b/docs/api-reference/teamspace/update-teamspace-detail.md index 28fbe7b3..59b01d40 100644 --- a/docs/api-reference/teamspace/update-teamspace-detail.md +++ b/docs/api-reference/teamspace/update-teamspace-detail.md @@ -89,6 +89,14 @@ ID of the user who leads the teamspace.
+
+ +### Scopes + +`teamspaces:write` + +
+
@@ -99,6 +107,7 @@ ID of the user who leads the teamspace. curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/teamspaces/{teamspace_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "example-name", diff --git a/docs/api-reference/user/get-current-user.md b/docs/api-reference/user/get-current-user.md index 6668a175..942a0112 100644 --- a/docs/api-reference/user/get-current-user.md +++ b/docs/api-reference/user/get-current-user.md @@ -17,6 +17,14 @@ keywords: plane, plane api, rest api, api integration Retrieves information about the currently authenticated user. +
+ +### Scopes + +`profile:read` + +
+
diff --git a/docs/api-reference/worklogs/create-worklog.md b/docs/api-reference/worklogs/create-worklog.md index 2b739b44..60536417 100644 --- a/docs/api-reference/worklogs/create-worklog.md +++ b/docs/api-reference/worklogs/create-worklog.md @@ -65,6 +65,14 @@ Time spent on the issue in minutes.
+
+ +### Scopes + +`projects.work_items.worklogs:write` + +
+
@@ -75,6 +83,7 @@ Time spent on the issue in minutes. curl -X POST \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/worklogs/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "example-description", diff --git a/docs/api-reference/worklogs/delete-worklog.md b/docs/api-reference/worklogs/delete-worklog.md index 8abee01a..eac39b7e 100644 --- a/docs/api-reference/worklogs/delete-worklog.md +++ b/docs/api-reference/worklogs/delete-worklog.md @@ -50,6 +50,14 @@ The unique identifier of the worklog
+
+ +### Scopes + +`projects.work_items.worklogs:write` + +
+
@@ -59,7 +67,8 @@ The unique identifier of the worklog ```bash curl -X DELETE \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/worklogs/{worklog_id}/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/worklogs/get-total-time.md b/docs/api-reference/worklogs/get-total-time.md index 8b7723a6..40b454b4 100644 --- a/docs/api-reference/worklogs/get-total-time.md +++ b/docs/api-reference/worklogs/get-total-time.md @@ -38,6 +38,14 @@ The unique identifier of the project
+
+ +### Scopes + +`projects.work_items.worklogs:read` + +
+
@@ -47,7 +55,8 @@ The unique identifier of the project ```bash curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/total-worklogs/" \ - -H "X-API-Key: $PLANE_API_KEY" + -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/worklogs/get-worklogs-for-issue.md b/docs/api-reference/worklogs/get-worklogs-for-issue.md index fd775ec0..93c697ba 100644 --- a/docs/api-reference/worklogs/get-worklogs-for-issue.md +++ b/docs/api-reference/worklogs/get-worklogs-for-issue.md @@ -44,6 +44,14 @@ The unique identifier of the work item
+
+ +### Scopes + +`projects.work_items.worklogs:read` + +
+
@@ -54,6 +62,7 @@ The unique identifier of the work item curl -X GET \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/worklogs/" \ -H "X-API-Key: $PLANE_API_KEY" + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ ``` diff --git a/docs/api-reference/worklogs/update-worklog.md b/docs/api-reference/worklogs/update-worklog.md index 720b8d1d..c6f6d5a7 100644 --- a/docs/api-reference/worklogs/update-worklog.md +++ b/docs/api-reference/worklogs/update-worklog.md @@ -71,6 +71,14 @@ Time spent on the issue in minutes
+
+ +### Scopes + +`projects.work_items.worklogs:write` + +
+
@@ -81,6 +89,7 @@ Time spent on the issue in minutes curl -X PATCH \ "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/work-items/work-item-uuid/worklogs/{worklog_id}/" \ -H "X-API-Key: $PLANE_API_KEY" \ + # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "example-description", diff --git a/docs/dev-tools/agents/building-an-agent.md b/docs/dev-tools/agents/building-an-agent.md index edaff1df..60338bbf 100644 --- a/docs/dev-tools/agents/building-an-agent.md +++ b/docs/dev-tools/agents/building-an-agent.md @@ -13,14 +13,14 @@ Plane Agents are currently in **Beta**. Please send any feedback to support@plan Before building an agent, make sure you have completed the following: -1. **Build a Plane app** — Follow the [Build a Plane App](/dev-tools/build-plane-app) guide to understand OAuth flows, deployment, and webhook handling. +1. **Build a Plane app** — Follow the [Build a Plane App](/dev-tools/build-plane-app/overview) guide to understand OAuth flows, deployment, and webhook handling. -2. **Get your bot token** — Complete the [Bot Token Flow](/dev-tools/build-plane-app#bot-token-flow) to obtain a `bot_token` for your agent. This token is used for all API calls. +2. **Get your bot token** — Complete the [Bot Token Flow](/dev-tools/build-plane-app/choose-token-flow) to obtain a `bot_token` for your agent. This token is used for all API calls. -3. **Set up webhook handling** — Ensure your server can [receive and verify webhooks](/dev-tools/build-plane-app#handling-webhooks) from Plane. +3. **Set up webhook handling** — Ensure your server can [receive and verify webhooks](/dev-tools/build-plane-app/webhooks) from Plane. ::: info -This guide assumes you have a working OAuth app with webhook handling. If not, complete the [Build a Plane App](/dev-tools/build-plane-app) guide first. +This guide assumes you have a working OAuth app with webhook handling. If not, complete the [Build a Plane App](/dev-tools/build-plane-app/overview) guide first. ::: ## Creating an agent @@ -33,7 +33,7 @@ Building a Plane agent involves three main steps: ### OAuth app creation -To create an agent, you first need to [register an OAuth application](/dev-tools/build-plane-app#create-an-oauth-application) with the **Enable App Mentions** checkbox enabled. +To create an agent, you first need to [register an OAuth application](/dev-tools/build-plane-app/create-oauth-application) with the **Enable App Mentions** checkbox enabled. 1. Navigate to `https://app.plane.so//settings/integrations/` 2. Click on **Build your own** button @@ -60,7 +60,7 @@ After installation, your agent appears alongside workspace members in the mentio ## Agent interaction -Once your agent is installed via the [OAuth consent flow](/dev-tools/build-plane-app#bot-token-flow) and users start mentioning it, you need to handle the interactions through Agent Runs and Activities. +Once your agent is installed via the [OAuth consent flow](/dev-tools/build-plane-app/choose-token-flow) and users start mentioning it, you need to handle the interactions through Agent Runs and Activities. ### AgentRun diff --git a/docs/dev-tools/build-plane-app.md b/docs/dev-tools/build-plane-app.md deleted file mode 100644 index 60a21bb8..00000000 --- a/docs/dev-tools/build-plane-app.md +++ /dev/null @@ -1,637 +0,0 @@ ---- -title: Build a Plane App -description: Build and integrate an app with Plane using OAuth 2.0 authentication. ---- - -# Build a Plane App - -::: info -Plane apps are currently in **Beta**. Please send any feedback to support@plane.so. -::: - -## Overview - -Plane uses OAuth 2.0 to allow applications to access workspace data on behalf of users or as an autonomous bot. This guide covers how to register your app and implement the OAuth flow. - -## Create an OAuth Application - -1. Navigate to **Workspace Settings** → **Integrations** (`https://app.plane.so//settings/integrations/`) -2. Click **Build your own** -3. Fill in the required details: - -| Field | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------ | -| **App Name** | Display name shown to users | -| **Setup URL** | Entry point when users install your app. Your app redirects users to Plane's consent screen from here. | -| **Redirect URI** | Callback URL where Plane sends users after they approve access, along with the authorization code. | -| **Webhook URL** | Endpoint for receiving event notifications | - -4. For agents that respond to @mentions, enable **"Enable App Mentions"** -5. Save and store your **Client ID** and **Client Secret** securely - -::: warning -Never expose your Client Secret in client-side code or commit it to version control. -::: - -## Choose Your Flow - -Plane supports two OAuth flows: - -| Flow | Use When | Token Type | -| ----------------------------------- | ---------------------------------------------- | -------------- | -| **Bot Token** (Client Credentials) | Agents, webhooks, automation, background tasks | `bot_token` | -| **User Token** (Authorization Code) | Actions on behalf of a specific user | `access_token` | - -::: info -Most integrations should use the **Bot Token flow**. Use User Token only when you need to perform actions as a specific user. -::: - ---- - -## Bot Token Flow - -Use this flow for agents, webhook handlers, and automation that acts autonomously. - -```mermaid -sequenceDiagram - participant User - participant Plane - participant YourApp - - User->>YourApp: Clicks "Install" - YourApp->>Plane: Redirects to consent screen - Plane->>User: Shows consent screen - User->>Plane: Approves - Plane->>YourApp: Redirects with app_installation_id - YourApp->>Plane: POST /auth/o/token/ (client_credentials) - Plane->>YourApp: Returns bot_token - YourApp->>YourApp: Store credentials -``` - -### 1. Redirect to Authorization - -When a user clicks "Install", redirect them to Plane's consent screen: - -``` -GET https://api.plane.so/auth/o/authorize-app/ - ?client_id=YOUR_CLIENT_ID - &response_type=code - &redirect_uri=https://your-app.com/callback -``` - -### 2. Handle the Callback - -After the user approves, Plane redirects to your Redirect URI with: - -| Parameter | Description | -| --------------------- | ----------------------------------------- | -| `app_installation_id` | Unique identifier for this installation | -| `code` | Authorization code (not used in bot flow) | - -### 3. Exchange for Bot Token - -``` -POST https://api.plane.so/auth/o/token/ -Content-Type: application/x-www-form-urlencoded -Authorization: Basic base64(client_id:client_secret) - -grant_type=client_credentials -&app_installation_id=APP_INSTALLATION_ID -``` - -**Response:** - -```json -{ - "access_token": "pln_bot_xxxxxxxxxxxx", - "token_type": "Bearer", - "expires_in": 86400 -} -``` - -### 4. Get Workspace Details - -``` -GET https://api.plane.so/auth/o/app-installation/?id=APP_INSTALLATION_ID -Authorization: Bearer YOUR_BOT_TOKEN -``` - -**Response:** - -```json -[ - { - "id": "installation-uuid", - "workspace": "workspace-uuid", - "workspace_detail": { - "name": "My Workspace", - "slug": "my-workspace" - }, - "app_bot": "bot-user-uuid", - "status": "installed" - } -] -``` - -Store the `workspace_detail.slug` for API calls and `app_installation_id` for token refresh. - -### 5. Refresh Bot Token - -Bot tokens expire. Request a new one using the stored `app_installation_id`: - -``` -POST https://api.plane.so/auth/o/token/ -Content-Type: application/x-www-form-urlencoded -Authorization: Basic base64(client_id:client_secret) - -grant_type=client_credentials -&app_installation_id=APP_INSTALLATION_ID -``` - ---- - -## User Token Flow - -Use this flow when your app needs to act on behalf of a specific user. - -```mermaid -sequenceDiagram - participant User - participant Plane - participant YourApp - - User->>YourApp: Clicks "Connect" - YourApp->>Plane: Redirects to consent screen - Plane->>User: Shows consent screen - User->>Plane: Approves - Plane->>YourApp: Redirects with code - YourApp->>Plane: POST /auth/o/token/ (authorization_code) - Plane->>YourApp: Returns access_token + refresh_token - YourApp->>YourApp: Store tokens for user -``` - -### 1. Redirect to Authorization - -``` -GET https://api.plane.so/auth/o/authorize-app/ - ?client_id=YOUR_CLIENT_ID - &response_type=code - &redirect_uri=https://your-app.com/callback - &state=RANDOM_STATE_VALUE -``` - -::: info -Include a random `state` parameter to prevent CSRF attacks. Verify it matches when handling the callback. -::: - -### 2. Handle the Callback - -After approval, Plane redirects to your Redirect URI with: - -| Parameter | Description | -| --------- | ------------------------------------------ | -| `code` | Authorization code to exchange for tokens | -| `state` | Your state parameter (verify this matches) | - -### 3. Exchange Code for Tokens - -``` -POST https://api.plane.so/auth/o/token/ -Content-Type: application/x-www-form-urlencoded - -grant_type=authorization_code -&code=AUTHORIZATION_CODE -&client_id=YOUR_CLIENT_ID -&client_secret=YOUR_CLIENT_SECRET -&redirect_uri=https://your-app.com/callback -``` - -**Response:** - -```json -{ - "access_token": "pln_xxxxxxxxxxxx", - "refresh_token": "pln_refresh_xxxxxxxxxxxx", - "token_type": "Bearer", - "expires_in": 86400 -} -``` - -### 4. Refresh User Token - -``` -POST https://api.plane.so/auth/o/token/ -Content-Type: application/x-www-form-urlencoded - -grant_type=refresh_token -&refresh_token=YOUR_REFRESH_TOKEN -&client_id=YOUR_CLIENT_ID -&client_secret=YOUR_CLIENT_SECRET -``` - ---- - -## Making API Requests - -Include the token in the `Authorization` header: - -``` -GET https://api.plane.so/api/v1/workspaces/{workspace_slug}/projects/ -Authorization: Bearer YOUR_TOKEN -``` - -See the [API Reference](/api-reference/introduction) for available endpoints. - ---- - -## Handling Webhooks - -When events occur in Plane, webhooks are sent to your Webhook URL. - -### Webhook Headers - -| Header | Description | -| ------------------- | ------------------------------------------- | -| `X-Plane-Delivery` | Unique delivery ID | -| `X-Plane-Event` | Event type (e.g., `issue`, `issue_comment`) | -| `X-Plane-Signature` | HMAC-SHA256 signature for verification | - -### Verify Signature - -Always verify the `X-Plane-Signature` header: - -:::tabs key:language -== Python {#python} - -```python -import hmac -import hashlib - -def verify_signature(payload: bytes, signature: str, secret: str) -> bool: - expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest() - return hmac.compare_digest(expected, signature) -``` - -== TypeScript {#typescript} - -```typescript -import crypto from "crypto"; - -function verifySignature(payload: string, signature: string, secret: string): boolean { - const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex"); - return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); -} -``` - -::: - -### Webhook Payload - -```json -{ - "event": "issue", - "action": "created", - "webhook_id": "webhook-uuid", - "workspace_id": "workspace-uuid", - "data": { ... }, - "activity": { - "actor": { "id": "user-uuid", "display_name": "John Doe" } - } -} -``` - -See [Webhook Events](/dev-tools/intro-webhooks) for all event types. - ---- - -## Local Development - -For local development, use [ngrok](https://ngrok.com) to expose your server: - -```bash -ngrok http 3000 -``` - -Use the generated URL (e.g., `https://abc123.ngrok.io`) for your Setup URL, Redirect URI, and Webhook URL. - -::: info -Free ngrok URLs change on restart. Update your app settings when the URL changes. -::: - ---- - -## SDKs - -Official SDKs provide OAuth helpers and typed API clients: - -| Language | Package | -| -------- | ------------------------------------------------------------------------------------ | -| Node.js | [@makeplane/plane-node-sdk](https://www.npmjs.com/package/@makeplane/plane-node-sdk) | -| Python | [plane-sdk](https://pypi.org/project/plane-sdk/) | - -```bash -npm install @makeplane/plane-node-sdk -# or -pip install plane-sdk -``` - -::: details SDK OAuth Helper Methods - -**Node.js:** - -```typescript -import { OAuthClient } from "@makeplane/plane-node-sdk"; - -const oauth = new OAuthClient({ - clientId: "your_client_id", - clientSecret: "your_client_secret", - redirectUri: "https://your-app.com/callback", -}); - -// Generate authorization URL -const authUrl = oauth.getAuthorizationUrl("code", "state"); - -// Exchange for bot token -const token = await oauth.getBotToken(appInstallationId); - -// Exchange code for user token -const userToken = await oauth.exchangeCodeForToken(code); - -// Refresh user token -const newToken = await oauth.getRefreshToken(refreshToken); -``` - -**Python:** - -```python -from plane.client import OAuthClient - -oauth = OAuthClient( - client_id="your_client_id", - client_secret="your_client_secret", -) - -# Generate authorization URL -auth_url = oauth.get_authorization_url(redirect_uri="...", state="state") - -# Exchange for bot token -token = oauth.get_client_credentials_token(app_installation_id=app_installation_id) - -# Exchange code for user token -user_token = oauth.exchange_code(code=code, redirect_uri=redirect_uri) - -# Refresh user token -new_token = oauth.refresh_token(refresh_token) -``` - -::: - ---- - -## Next Steps - -- [Build an Agent](/dev-tools/agents/overview) - Create AI agents that respond to @mentions -- [API Reference](/api-reference/introduction) - Explore the full Plane API -- [Webhook Events](/dev-tools/intro-webhooks) - All webhook event types -- [Example: PRD Agent](https://github.com/makeplane/prd-agent) - Complete agent implementation - ---- - -## Complete Examples - -::: details TypeScript (Express) - Full Implementation - -```typescript -import express from "express"; -import axios from "axios"; -import crypto from "crypto"; - -const app = express(); - -const CLIENT_ID = process.env.PLANE_CLIENT_ID!; -const CLIENT_SECRET = process.env.PLANE_CLIENT_SECRET!; -const REDIRECT_URI = process.env.PLANE_REDIRECT_URI!; -const WEBHOOK_SECRET = process.env.PLANE_WEBHOOK_SECRET!; -const PLANE_API_URL = process.env.PLANE_API_URL || "https://api.plane.so"; - -// In-memory storage (use a database in production) -const installations = new Map< - string, - { - botToken: string; - workspaceSlug: string; - appInstallationId: string; - } ->(); - -// Setup URL - redirect to Plane's consent screen -app.get("/oauth/setup", (req, res) => { - const params = new URLSearchParams({ - client_id: CLIENT_ID, - response_type: "code", - redirect_uri: REDIRECT_URI, - }); - res.redirect(`${PLANE_API_URL}/auth/o/authorize-app/?${params}`); -}); - -// OAuth callback - exchange app_installation_id for bot token -app.get("/oauth/callback", async (req, res) => { - const appInstallationId = req.query.app_installation_id as string; - - if (!appInstallationId) { - return res.status(400).send("Missing app_installation_id"); - } - - try { - const basicAuth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64"); - - // Exchange for bot token - const tokenRes = await axios.post( - `${PLANE_API_URL}/auth/o/token/`, - new URLSearchParams({ - grant_type: "client_credentials", - app_installation_id: appInstallationId, - }).toString(), - { - headers: { - Authorization: `Basic ${basicAuth}`, - "Content-Type": "application/x-www-form-urlencoded", - }, - } - ); - - const botToken = tokenRes.data.access_token; - - // Get workspace details - const installRes = await axios.get(`${PLANE_API_URL}/auth/o/app-installation/?id=${appInstallationId}`, { - headers: { Authorization: `Bearer ${botToken}` }, - }); - - const installation = installRes.data[0]; - const workspaceId = installation.workspace; - const workspaceSlug = installation.workspace_detail.slug; - - // Store credentials - installations.set(workspaceId, { botToken, workspaceSlug, appInstallationId }); - - console.log(`Installed in workspace: ${workspaceSlug}`); - res.send("Installation successful! You can close this window."); - } catch (error) { - console.error("OAuth error:", error); - res.status(500).send("Installation failed"); - } -}); - -// Webhook handler -app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { - const signature = req.headers["x-plane-signature"] as string; - const payload = req.body.toString(); - - // Verify signature - const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(payload).digest("hex"); - if (!crypto.timingSafeEqual(Buffer.from(signature || ""), Buffer.from(expected))) { - return res.status(403).send("Invalid signature"); - } - - const event = JSON.parse(payload); - console.log(`Received: ${event.event} ${event.action}`); - - // Get credentials for this workspace - const creds = installations.get(event.workspace_id); - if (creds) { - // Process the event with creds.botToken - } - - res.status(200).send("OK"); -}); - -app.listen(3000, () => console.log("Server running on http://localhost:3000")); -``` - -::: - -::: details Python (Flask) - Full Implementation - -```python -import os -import hmac -import hashlib -import base64 -import requests as http_requests -from flask import Flask, request, redirect -from urllib.parse import urlencode - -app = Flask(__name__) - -CLIENT_ID = os.getenv("PLANE_CLIENT_ID") -CLIENT_SECRET = os.getenv("PLANE_CLIENT_SECRET") -REDIRECT_URI = os.getenv("PLANE_REDIRECT_URI") -WEBHOOK_SECRET = os.getenv("PLANE_WEBHOOK_SECRET") -PLANE_API_URL = os.getenv("PLANE_API_URL", "https://api.plane.so") - -# In-memory storage (use a database in production) -installations = {} - - -@app.route("/oauth/setup") -def oauth_setup(): - """Redirect to Plane's consent screen.""" - params = urlencode({ - "client_id": CLIENT_ID, - "response_type": "code", - "redirect_uri": REDIRECT_URI, - }) - return redirect(f"{PLANE_API_URL}/auth/o/authorize-app/?{params}") - - -@app.route("/oauth/callback") -def oauth_callback(): - """Exchange app_installation_id for bot token.""" - app_installation_id = request.args.get("app_installation_id") - - if not app_installation_id: - return "Missing app_installation_id", 400 - - try: - # Exchange for bot token - credentials = f"{CLIENT_ID}:{CLIENT_SECRET}" - basic_auth = base64.b64encode(credentials.encode()).decode() - - token_response = http_requests.post( - f"{PLANE_API_URL}/auth/o/token/", - data={ - "grant_type": "client_credentials", - "app_installation_id": app_installation_id, - }, - headers={ - "Authorization": f"Basic {basic_auth}", - "Content-Type": "application/x-www-form-urlencoded", - }, - ) - token_response.raise_for_status() - bot_token = token_response.json()["access_token"] - - # Get workspace details - install_response = http_requests.get( - f"{PLANE_API_URL}/auth/o/app-installation/", - params={"id": app_installation_id}, - headers={"Authorization": f"Bearer {bot_token}"}, - ) - install_response.raise_for_status() - installation = install_response.json()[0] - - workspace_id = installation["workspace"] - workspace_slug = installation["workspace_detail"]["slug"] - - # Store credentials - installations[workspace_id] = { - "bot_token": bot_token, - "workspace_slug": workspace_slug, - "app_installation_id": app_installation_id, - } - - print(f"Installed in workspace: {workspace_slug}") - return "Installation successful! You can close this window." - - except Exception as e: - print(f"OAuth error: {e}") - return "Installation failed", 500 - - -@app.route("/webhook", methods=["POST"]) -def webhook(): - """Handle incoming webhooks.""" - signature = request.headers.get("X-Plane-Signature", "") - payload = request.get_data() - - # Verify signature - expected = hmac.new( - WEBHOOK_SECRET.encode(), payload, hashlib.sha256 - ).hexdigest() - - if not hmac.compare_digest(expected, signature): - return "Invalid signature", 403 - - event = request.get_json() - print(f"Received: {event['event']} {event['action']}") - - # Get credentials for this workspace - creds = installations.get(event["workspace_id"]) - if creds: - # Process the event with creds["bot_token"] - pass - - return "OK", 200 - - -if __name__ == "__main__": - app.run(port=3000) -``` - -::: - ---- - -## Publish to Marketplace - -Apps can be listed on the [Plane Marketplace](https://plane.so/marketplace/integrations). Contact [support@plane.so](mailto:support@plane.so) to list your app. diff --git a/docs/dev-tools/build-plane-app/choose-token-flow.md b/docs/dev-tools/build-plane-app/choose-token-flow.md new file mode 100644 index 00000000..4405b924 --- /dev/null +++ b/docs/dev-tools/build-plane-app/choose-token-flow.md @@ -0,0 +1,218 @@ +--- +title: Choose token flow +description: Decide between Bot Token and User Token flows and learn how to implement them. +--- + +# Choose token flow + +Plane supports two OAuth flows: + +| Flow | Use When | Token Type | +| ----------------------------------- | ---------------------------------------------- | -------------- | +| **Bot Token** (Client Credentials) | Agents, webhooks, automation, background tasks | `bot_token` | +| **User Token** (Authorization Code) | Actions on behalf of a specific user | `access_token` | + +::: info +Most integrations should use the **Bot Token flow**. Use User Token only when you need to perform actions as a specific user. +::: + +--- + +## Bot token flow + +Use this flow for agents, webhook handlers, and automation that acts autonomously. + +```mermaid +sequenceDiagram + participant User + participant Plane + participant YourApp + + User->>YourApp: Clicks "Install" + YourApp->>Plane: Redirects to consent screen + Plane->>User: Shows consent screen + User->>Plane: Approves + Plane->>YourApp: Redirects with app_installation_id + YourApp->>Plane: POST /auth/o/token/ (client_credentials) + Plane->>YourApp: Returns bot_token + YourApp->>YourApp: Store credentials +``` + +### 1. Redirect to authorization + +When a user clicks "Install", redirect them to Plane's consent screen: + +``` +GET https://api.plane.so/auth/o/authorize-app/ + ?client_id=YOUR_CLIENT_ID + &response_type=code + &redirect_uri=https://your-app.com/callback +``` + +### 2. Handle the callback + +After the user approves, Plane redirects to your Redirect URI with: + +| Parameter | Description | +| --------------------- | ----------------------------------------- | +| `app_installation_id` | Unique identifier for this installation | +| `code` | Authorization code (not used in bot flow) | + +### 3. Exchange for bot token + +``` +POST https://api.plane.so/auth/o/token/ +Content-Type: application/x-www-form-urlencoded +Authorization: Basic base64(client_id:client_secret) + +grant_type=client_credentials +&app_installation_id=APP_INSTALLATION_ID +&scope=scopeA scopeB scopeC +``` + +**Response:** + +```json +{ + "access_token": "pln_bot_xxxxxxxxxxxx", + "token_type": "Bearer", + "expires_in": 86400, + "scope": "scopeA scopeB scopeC" +} +``` + +### 4. Get workspace details + +``` +GET https://api.plane.so/auth/o/app-installation/?id=APP_INSTALLATION_ID +Authorization: Bearer YOUR_BOT_TOKEN +``` + +**Response:** + +```json +[ + { + "id": "installation-uuid", + "workspace": "workspace-uuid", + "workspace_detail": { + "name": "My Workspace", + "slug": "my-workspace" + }, + "app_bot": "bot-user-uuid", + "status": "installed" + } +] +``` + +Store the `workspace_detail.slug` for API calls and `app_installation_id` for token refresh. + +### 5. Refresh bot token + +Bot tokens expire. Request a new one using the stored `app_installation_id`: + +``` +POST https://api.plane.so/auth/o/token/ +Content-Type: application/x-www-form-urlencoded +Authorization: Basic base64(client_id:client_secret) + +grant_type=client_credentials +&app_installation_id=APP_INSTALLATION_ID +&scope=scopeA scopeB scopeC +``` + +--- + +## User token flow + +Use this flow when your app needs to act on behalf of a specific user. + +```mermaid +sequenceDiagram + participant User + participant Plane + participant YourApp + + User->>YourApp: Clicks "Connect" + YourApp->>Plane: Redirects to consent screen + Plane->>User: Shows consent screen + User->>Plane: Approves + Plane->>YourApp: Redirects with code + YourApp->>Plane: POST /auth/o/token/ (authorization_code) + Plane->>YourApp: Returns access_token + refresh_token + YourApp->>YourApp: Store tokens for user +``` + +### 1. Redirect to authorization + +``` +GET https://api.plane.so/auth/o/authorize-app/ + ?client_id=YOUR_CLIENT_ID + &response_type=code + &redirect_uri=https://your-app.com/callback + &state=RANDOM_STATE_VALUE + &scope=scopeA scopeB scopeC +``` + +::: info +Include a random `state` parameter to prevent CSRF attacks. Verify it matches when handling the callback. +::: + +### 2. Handle the callback + +After approval, Plane redirects to your Redirect URI with: + +| Parameter | Description | +| --------- | ------------------------------------------ | +| `code` | Authorization code to exchange for tokens | +| `state` | Your state parameter (verify this matches) | + +### 3. Exchange code for tokens + +``` +POST https://api.plane.so/auth/o/token/ +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code +&code=AUTHORIZATION_CODE +&client_id=YOUR_CLIENT_ID +&client_secret=YOUR_CLIENT_SECRET +&redirect_uri=https://your-app.com/callback +``` + +**Response:** + +```json +{ + "access_token": "pln_xxxxxxxxxxxx", + "refresh_token": "pln_refresh_xxxxxxxxxxxx", + "token_type": "Bearer", + "expires_in": 86400, + "scope": "scopeA scopeB scopeC" +} +``` + +### 4. Refresh user token + +``` +POST https://api.plane.so/auth/o/token/ +Content-Type: application/x-www-form-urlencoded + +grant_type=refresh_token +&refresh_token=YOUR_REFRESH_TOKEN +&client_id=YOUR_CLIENT_ID +&client_secret=YOUR_CLIENT_SECRET +``` + +--- + +## Making API requests + +Include the token in the `Authorization` header: + +``` +GET https://api.plane.so/api/v1/workspaces/{workspace_slug}/projects/ +Authorization: Bearer YOUR_TOKEN +``` + +See the [API Reference](/api-reference/introduction) for available endpoints. diff --git a/docs/dev-tools/build-plane-app/create-oauth-application.md b/docs/dev-tools/build-plane-app/create-oauth-application.md new file mode 100644 index 00000000..f5a6b4dd --- /dev/null +++ b/docs/dev-tools/build-plane-app/create-oauth-application.md @@ -0,0 +1,25 @@ +--- +title: Create an OAuth Application +description: Register your app to get Client ID and Secret. +--- + +# Create an OAuth Application + +1. Navigate to **Workspace Settings** → **Integrations**. `https://app.plane.so//settings/integrations/` +2. Click **Build your own**. +3. Fill in the required details: + +| Field | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------ | +| **App Name** | Display name shown to users | +| **Setup URL** | Entry point when users install your app. Your app redirects users to Plane's consent screen from here. | +| **Redirect URI** | Callback URL where Plane sends users after they approve access, along with the authorization code. | +| **Webhook URL** | Endpoint for receiving event notifications | + +4. For agents that respond to @mentions, enable **"Enable App Mentions"**. +5. Save and store your **Client ID** and **Client Secret** securely. +6. Select the scopes you need for your app from the **Scopes & Permissions** section. See [OAuth Scopes](/dev-tools/build-plane-app/oauth-scopes) for more information on the available scopes. + +::: warning +Never expose your Client Secret in client-side code or commit it to version control. +::: diff --git a/docs/dev-tools/build-plane-app/examples.md b/docs/dev-tools/build-plane-app/examples.md new file mode 100644 index 00000000..c8d803ed --- /dev/null +++ b/docs/dev-tools/build-plane-app/examples.md @@ -0,0 +1,244 @@ +--- +title: Complete examples +description: Full code examples for Node.js (Express) and Python (Flask). +--- + +# Complete examples + +::: code-group + +```typescript [TypeScript (Express)] +import express from "express"; +import axios from "axios"; +import crypto from "crypto"; + +const app = express(); + +const CLIENT_ID = process.env.PLANE_CLIENT_ID!; +const CLIENT_SECRET = process.env.PLANE_CLIENT_SECRET!; +const REDIRECT_URI = process.env.PLANE_REDIRECT_URI!; +const WEBHOOK_SECRET = process.env.PLANE_WEBHOOK_SECRET!; +const PLANE_API_URL = process.env.PLANE_API_URL || "https://api.plane.so"; + +// In-memory storage (use a database in production) +const installations = new Map< + string, + { + botToken: string; + workspaceSlug: string; + appInstallationId: string; + } +>(); + +// Setup URL - redirect to Plane's consent screen +app.get("/oauth/setup", (req, res) => { + const params = new URLSearchParams({ + client_id: CLIENT_ID, + response_type: "code", + redirect_uri: REDIRECT_URI, + }); + res.redirect(`${PLANE_API_URL}/auth/o/authorize-app/?${params}`); +}); + +// OAuth callback - exchange app_installation_id for bot token +app.get("/oauth/callback", async (req, res) => { + const appInstallationId = req.query.app_installation_id as string; + + if (!appInstallationId) { + return res.status(400).send("Missing app_installation_id"); + } + + try { + const basicAuth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64"); + + // Exchange for bot token + const tokenRes = await axios.post( + `${PLANE_API_URL}/auth/o/token/`, + new URLSearchParams({ + grant_type: "client_credentials", + app_installation_id: appInstallationId, + }).toString(), + { + headers: { + Authorization: `Basic ${basicAuth}`, + "Content-Type": "application/x-www-form-urlencoded", + }, + } + ); + + const botToken = tokenRes.data.access_token; + + // Get workspace details + const installRes = await axios.get(`${PLANE_API_URL}/auth/o/app-installation/?id=${appInstallationId}`, { + headers: { Authorization: `Bearer ${botToken}` }, + }); + + const installation = installRes.data[0]; + const workspaceId = installation.workspace; + const workspaceSlug = installation.workspace_detail.slug; + + // Store credentials + installations.set(workspaceId, { botToken, workspaceSlug, appInstallationId }); + + console.log(`Installed in workspace: ${workspaceSlug}`); + res.send("Installation successful! You can close this window."); + } catch (error) { + console.error("OAuth error:", error); + res.status(500).send("Installation failed"); + } +}); + +// Webhook handler +app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { + const signature = req.headers["x-plane-signature"] as string; + const payload = req.body.toString(); + + // Verify signature + const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(payload).digest("hex"); + if (!crypto.timingSafeEqual(Buffer.from(signature || ""), Buffer.from(expected))) { + return res.status(403).send("Invalid signature"); + } + + const event = JSON.parse(payload); + console.log(`Received: ${event.event} ${event.action}`); + + // Get credentials for this workspace + const creds = installations.get(event.workspace_id); + if (creds) { + // Process the event with creds.botToken + } + + res.status(200).send("OK"); +}); + +app.listen(3000, () => console.log("Server running on http://localhost:3000")); +``` + +```python [Python (Flask)] +import os +import hmac +import hashlib +import base64 +import requests as http_requests +from flask import Flask, request, redirect +from urllib.parse import urlencode + +app = Flask(__name__) + +CLIENT_ID = os.getenv("PLANE_CLIENT_ID") +CLIENT_SECRET = os.getenv("PLANE_CLIENT_SECRET") +REDIRECT_URI = os.getenv("PLANE_REDIRECT_URI") +WEBHOOK_SECRET = os.getenv("PLANE_WEBHOOK_SECRET") +PLANE_API_URL = os.getenv("PLANE_API_URL", "https://api.plane.so") + +# In-memory storage (use a database in production) +installations = {} + + +@app.route("/oauth/setup") +def oauth_setup(): + """Redirect to Plane's consent screen.""" + params = urlencode({ + "client_id": CLIENT_ID, + "response_type": "code", + "redirect_uri": REDIRECT_URI, + }) + return redirect(f"{PLANE_API_URL}/auth/o/authorize-app/?{params}") + + +@app.route("/oauth/callback") +def oauth_callback(): + """Exchange app_installation_id for bot token.""" + app_installation_id = request.args.get("app_installation_id") + + if not app_installation_id: + return "Missing app_installation_id", 400 + + try: + # Exchange for bot token + credentials = f"{CLIENT_ID}:{CLIENT_SECRET}" + basic_auth = base64.b64encode(credentials.encode()).decode() + + token_response = http_requests.post( + f"{PLANE_API_URL}/auth/o/token/", + data={ + "grant_type": "client_credentials", + "app_installation_id": app_installation_id, + }, + headers={ + "Authorization": f"Basic {basic_auth}", + "Content-Type": "application/x-www-form-urlencoded", + }, + ) + token_response.raise_for_status() + bot_token = token_response.json()["access_token"] + + # Get workspace details + install_response = http_requests.get( + f"{PLANE_API_URL}/auth/o/app-installation/", + params={"id": app_installation_id}, + headers={"Authorization": f"Bearer {bot_token}"}, + ) + install_response.raise_for_status() + installation = install_response.json()[0] + + workspace_id = installation["workspace"] + workspace_slug = installation["workspace_detail"]["slug"] + + # Store credentials + installations[workspace_id] = { + "bot_token": bot_token, + "workspace_slug": workspace_slug, + "app_installation_id": app_installation_id, + } + + print(f"Installed in workspace: {workspace_slug}") + return "Installation successful! You can close this window." + + except Exception as e: + print(f"OAuth error: {e}") + return "Installation failed", 500 + + +@app.route("/webhook", methods=["POST"]) +def webhook(): + """Handle incoming webhooks.""" + signature = request.headers.get("X-Plane-Signature", "") + payload = request.get_data() + + # Verify signature + expected = hmac.new( + WEBHOOK_SECRET.encode(), payload, hashlib.sha256 + ).hexdigest() + + if not hmac.compare_digest(expected, signature): + return "Invalid signature", 403 + + event = request.get_json() + print(f"Received: {event['event']} {event['action']}") + + # Get credentials for this workspace + creds = installations.get(event["workspace_id"]) + if creds: + # Process the event with creds["bot_token"] + pass + + return "OK", 200 + + +if __name__ == "__main__": + app.run(port=3000) +``` + +::: + +## Next Steps + +- [Build an Agent](/dev-tools/agents/overview) - Create AI agents that respond to @mentions +- [API Reference](/api-reference/introduction) - Explore the full Plane API +- [Webhook Events](/dev-tools/intro-webhooks) - All webhook event types +- [Example: PRD Agent](https://github.com/makeplane/prd-agent) - Complete agent implementation + +## Publish to Marketplace + +Apps can be listed on the [Plane Marketplace](https://plane.so/marketplace/integrations). Contact [support@plane.so](mailto:support@plane.so) to list your app. \ No newline at end of file diff --git a/docs/dev-tools/build-plane-app/oauth-scopes.md b/docs/dev-tools/build-plane-app/oauth-scopes.md new file mode 100644 index 00000000..f12a44df --- /dev/null +++ b/docs/dev-tools/build-plane-app/oauth-scopes.md @@ -0,0 +1,124 @@ +--- +title: OAuth Scopes +description: All OAuth scopes available when building a Plane app. +--- + +# OAuth scopes + +This document lists all OAuth scopes available when building a Plane app. Request only the scopes your app needs. + +## Project scopes + +| Scope | Description | +|-------|-------------| +| `projects:read` | Read projects | +| `projects:write` | Create and update projects | +| `projects.features:read` | Read project features | +| `projects.features:write` | Create and update project features | +| `projects.members:read` | Read project members | +| `projects.members:write` | Manage project members | +| `projects.states:read` | Read project states | +| `projects.states:write` | Create and update project states | +| `projects.labels:read` | Read project labels | +| `projects.labels:write` | Create and update project labels | +| `projects.intakes:read` | Read project intakes | +| `projects.intakes:write` | Create and update project intakes | +| `projects.epics:read` | Read project epics | +| `projects.epics:write` | Create and update project epics | +| `projects.cycles:read` | Read project cycles | +| `projects.cycles:write` | Create and update project cycles | +| `projects.pages:read` | Read project pages | +| `projects.pages:write` | Create and update project pages | +| `projects.modules:read` | Read project modules | +| `projects.modules:write` | Create and update project modules | +| `projects.work_items:read` | Read project work items | +| `projects.work_items:write` | Create and update project work items | +| `projects.work_items.comments:read` | Read work item comments | +| `projects.work_items.comments:write` | Create and update work item comments | +| `projects.work_items.attachments:read` | Read work item attachments | +| `projects.work_items.attachments:write` | Create and update work item attachments | +| `projects.work_items.links:read` | Read work item links | +| `projects.work_items.links:write` | Create and update work item links | +| `projects.work_items.relations:read` | Read work item relations | +| `projects.work_items.relations:write` | Create and update work item relations | +| `projects.work_items.activities:read` | Read work item activities | +| `projects.work_items.activities:write` | Create and update work item activities | +| `projects.work_items.worklogs:read` | Read work item worklogs | +| `projects.work_items.worklogs:write` | Create and update work item worklogs | +| `projects.work_item_types:read` | Read work item types | +| `projects.work_item_types:write` | Create and update work item types | +| `projects.work_item_properties:read` | Read work item properties | +| `projects.work_item_properties:write` | Create and update work item properties | +| `projects.work_item_property_options:read` | Read work item property options | +| `projects.work_item_property_options:write` | Create and update work item property options | +| `projects.work_item_property_values:read` | Read work item property values | +| `projects.work_item_property_values:write` | Create and update work item property values | +| `projects.milestones:read` | Read project milestones | +| `projects.milestones:write` | Create and update project milestones | + +## Wiki scopes + +| Scope | Description | +|-------|-------------| +| `wiki.pages:read` | Read wiki pages | +| `wiki.pages:write` | Create and update wiki pages | + +## Customer scopes + +| Scope | Description | +|-------|-------------| +| `customers:read` | Read customers | +| `customers:write` | Create and update customers | +| `customers.requests:read` | Read customer requests | +| `customers.requests:write` | Create and update customer requests | +| `customers.properties:read` | Read customer properties | +| `customers.properties:write` | Create and update customer properties | +| `customers.property_values:read` | Read customer property values | +| `customers.property_values:write` | Create and update customer property values | +| `customers.work_items:read` | Read customer work items | +| `customers.work_items:write` | Create and update customer work items | + +## Initiatives scopes + +| Scope | Description | +|-------|-------------| +| `initiatives:read` | Read initiatives | +| `initiatives:write` | Create and update initiatives | +| `initiatives.projects:read` | Read initiative projects | +| `initiatives.projects:write` | Create and update initiative projects | +| `initiatives.epics:read` | Read initiative epics | +| `initiatives.epics:write` | Create and update initiative epics | +| `initiatives.labels:read` | Read initiative labels | +| `initiatives.labels:write` | Create and update initiative labels | + +## Workspace scopes + +| Scope | Description | +|-------|-------------| +| `workspaces.members:read` | Read workspace members | +| `workspaces.features:read` | Read workspace features | +| `workspaces.features:write` | Create and update workspace features | + +## Stickies scopes + +| Scope | Description | +|-------|-------------| +| `stickies:read` | Read stickies | +| `stickies:write` | Create and update stickies | + +## Teamspaces scopes + +| Scope | Description | +|-------|-------------| +| `teamspaces:read` | Read teamspaces | +| `teamspaces:write` | Create and update teamspaces | +| `teamspaces.projects:read` | Read teamspace projects | +| `teamspaces.projects:write` | Create and update teamspace projects | +| `teamspaces.members:read` | Read teamspace members | +| `teamspaces.members:write` | Create and update teamspace members | + +## Profile scopes + +| Scope | Description | +|-------|-------------| +| `profile:read` | Read user profile | diff --git a/docs/dev-tools/build-plane-app/overview.md b/docs/dev-tools/build-plane-app/overview.md new file mode 100644 index 00000000..c7919bc1 --- /dev/null +++ b/docs/dev-tools/build-plane-app/overview.md @@ -0,0 +1,123 @@ +--- +title: Build a Plane App +description: Build and integrate an app with Plane using OAuth 2.0 authentication. +--- + +# Build a Plane app + +::: info +Plane apps are currently in **Beta**. Please send any feedback to support@plane.so. +::: + +## Overview + +Plane uses OAuth 2.0 to allow applications to access workspace data on behalf of users or as an autonomous bot. This comprehensive guide covers everything you need to build, integrate, and deploy apps that extend Plane's functionality. + +## What you can build + +Plane apps enable you to: + +- **AI Agents** - Create intelligent agents that respond to @mentions in work item comments +- **Workflow Automation** - Build bots that automate repetitive tasks across your workspace +- **Integrations** - Connect Plane with external tools and services +- **Custom Dashboards** - Build analytics and reporting tools using Plane's data +- **Webhook Handlers** - React to events in real-time as they happen in Plane + +## Key concepts + +### OAuth 2.0 flows + +Plane supports two authentication flows: + +- **Bot Token Flow** (Client Credentials) - For autonomous apps, agents, and webhooks that act independently +- **User Token Flow** (Authorization Code) - For apps that need to act on behalf of specific users + +Most integrations should use the **Bot Token flow**. See [Choose Your Flow](/dev-tools/build-plane-app/choose-token-flow) for detailed implementation guides. + +### App components + +A complete Plane app typically includes: + +1. **OAuth Application** - Registered in Plane with Client ID and Secret +2. **Setup URL** - Entry point where users begin the installation process +3. **Redirect URI** - Callback endpoint that receives authorization codes +4. **Webhook URL** - Endpoint for receiving real-time event notifications +5. **API Integration** - Code that interacts with Plane's REST API + +## Getting started + +Follow these steps to build your first Plane app: + +### 1. Create an OAuth application + +Register your app in Plane to get credentials: +- Navigate to **Workspace Settings** → **Integrations** +- Configure your app's URLs and permissions +- Store your **Client ID** and **Client Secret** securely + +[Learn more →](/dev-tools/build-plane-app/create-oauth-application) + +### 2. Choose your authentication flow + +Decide between Bot Token or User Token based on your use case: +- **Bot Token** - For agents, webhooks, and automation +- **User Token** - For user-specific actions and permissions + +[Learn more →](/dev-tools/build-plane-app/choose-token-flow) + +### 3. Implement OAuth + +Set up the OAuth flow to obtain access tokens: +- Redirect users to Plane's consent screen +- Handle the callback with authorization code +- Exchange code for access tokens +- Store tokens securely for API calls + +[Learn more →](/dev-tools/build-plane-app/choose-token-flow) + +### 4. Handle webhooks + +Set up webhook handlers to receive real-time events: +- Verify webhook signatures for security +- Process events like work item updates, comments, and more +- Respond to events with automated actions + +[Learn more →](/dev-tools/build-plane-app/webhooks) + +## Development tools + +::: tip Local Development +For local development, use [ngrok](https://ngrok.com) to expose your server: + +```bash +ngrok http 3000 +``` + +Use the generated URL (e.g., `https://abc123.ngrok.io`) for your Setup URL, Redirect URI, and Webhook URL. + +Free ngrok URLs change on restart. Update your app settings when the URL changes. +::: + +### Official SDKs + +Speed up development with official SDKs for Node.js and Python: +- OAuth helpers for token management +- Typed API clients for all endpoints +- Built-in error handling and retries + +[Learn more →](/dev-tools/build-plane-app/sdks) + +### Complete examples + +See full working implementations: +- TypeScript (Express) example +- Python (Flask) example +- OAuth flow, webhooks, and API integration + +[Learn more →](/dev-tools/build-plane-app/examples) + +## Quick links + +- [API Reference](/api-reference/introduction) - Explore all available endpoints +- [Build an Agent](/dev-tools/agents/overview) - Create AI agents for Plane +- [Webhook Events](/dev-tools/intro-webhooks) - All webhook event types diff --git a/docs/dev-tools/build-plane-app/sdks.md b/docs/dev-tools/build-plane-app/sdks.md new file mode 100644 index 00000000..069ba3e2 --- /dev/null +++ b/docs/dev-tools/build-plane-app/sdks.md @@ -0,0 +1,68 @@ +--- +title: SDKs +description: Official SDKs to build apps faster. +--- + +# SDKs + +Official SDKs provide OAuth helpers and typed API clients: + +| Language | Package | +| -------- | ------------------------------------------------------------------------------------ | +| Node.js | [@makeplane/plane-node-sdk](https://www.npmjs.com/package/@makeplane/plane-node-sdk) | +| Python | [plane-sdk](https://pypi.org/project/plane-sdk/) | + +```bash +npm install @makeplane/plane-node-sdk +# or +pip install plane-sdk +``` + +#### OAuth helper methods + +::: code-group + +```typescript [Node.js] +import { OAuthClient } from "@makeplane/plane-node-sdk"; + +const oauth = new OAuthClient({ + clientId: "your_client_id", + clientSecret: "your_client_secret", + redirectUri: "https://your-app.com/callback", +}); + +// Generate authorization URL +const authUrl = oauth.getAuthorizationUrl("code", "state"); + +// Exchange for bot token +const token = await oauth.getBotToken(appInstallationId); + +// Exchange code for user token +const userToken = await oauth.exchangeCodeForToken(code); + +// Refresh user token +const newToken = await oauth.getRefreshToken(refreshToken); +``` + +```python [Python] +from plane.client import OAuthClient + +oauth = OAuthClient( + client_id="your_client_id", + client_secret="your_client_secret", +) + +# Generate authorization URL +auth_url = oauth.get_authorization_url(redirect_uri="...", state="state") + +# Exchange for bot token +token = oauth.get_client_credentials_token(app_installation_id=app_installation_id) + +# Exchange code for user token +user_token = oauth.exchange_code(code=code, redirect_uri=redirect_uri) + +# Refresh user token +new_token = oauth.refresh_token(refresh_token) +``` + +::: diff --git a/docs/dev-tools/build-plane-app/webhooks.md b/docs/dev-tools/build-plane-app/webhooks.md new file mode 100644 index 00000000..3b51efcc --- /dev/null +++ b/docs/dev-tools/build-plane-app/webhooks.md @@ -0,0 +1,62 @@ +--- +title: Handling webhooks +description: How to receive and verify webhooks from Plane. +--- + +# Handling webhooks + +When events occur in Plane, webhooks are sent to your Webhook URL. + +## Webhook headers + +| Header | Description | +| ------------------- | ------------------------------------------- | +| `X-Plane-Delivery` | Unique delivery ID | +| `X-Plane-Event` | Event type (e.g., `issue`, `issue_comment`) | +| `X-Plane-Signature` | HMAC-SHA256 signature for verification | + +## Verify signature + +Always verify the `X-Plane-Signature` header: + +:::tabs key:language +== Python {#python} + +```python +import hmac +import hashlib + +def verify_signature(payload: bytes, signature: str, secret: str) -> bool: + expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest() + return hmac.compare_digest(expected, signature) +``` + +== TypeScript {#typescript} + +```typescript +import crypto from "crypto"; + +function verifySignature(payload: string, signature: string, secret: string): boolean { + const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex"); + return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); +} +``` + +::: + +## Webhook payload + +```json +{ + "event": "issue", + "action": "created", + "webhook_id": "webhook-uuid", + "workspace_id": "workspace-uuid", + "data": { ... }, + "activity": { + "actor": { "id": "user-uuid", "display_name": "John Doe" } + } +} +``` + +See [Webhook Events](/dev-tools/intro-webhooks) for all event types. diff --git a/docs/index.md b/docs/index.md index be784dcb..1dcf6b12 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,7 +34,7 @@ features: - icon: 🔌 title: OAuth Apps details: Build custom integrations using OAuth 2.0. Complete guides for app registration, token management, and API access. - link: /dev-tools/build-plane-app + link: /dev-tools/build-plane-app/overview linkText: Build an app - icon: 🤖 title: MCP Server