From d33646fe9a458319ca0774c86bf14b8331ea70e2 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Mon, 12 Aug 2024 16:17:30 +0200 Subject: [PATCH 1/3] docs: delete projects --- docs/concepts/personal-access-token.mdx | 2 +- docs/guides/delete-project.mdx | 17 +++++++++++++++++ src/sidebar.js | 1 + 3 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 docs/guides/delete-project.mdx diff --git a/docs/concepts/personal-access-token.mdx b/docs/concepts/personal-access-token.mdx index 0153a2c83..124f05290 100644 --- a/docs/concepts/personal-access-token.mdx +++ b/docs/concepts/personal-access-token.mdx @@ -144,7 +144,7 @@ create, read, update, delete. | Base URL | `api.console.ory.sh` | `$PROJECT_SLUG.projects.oryapis.com` | | Create projects | Yes | No | | Change project configurations, including the identity, oauth2, and permission service configuration | Yes | No | -| Delete projects | No | No | +| Delete projects | Yes | No | | List and invite members | Yes | No | | CRUD B2B SSO organizations | Yes | No | | CRUD project API keys | Yes | No | diff --git a/docs/guides/delete-project.mdx b/docs/guides/delete-project.mdx new file mode 100644 index 000000000..a848b6207 --- /dev/null +++ b/docs/guides/delete-project.mdx @@ -0,0 +1,17 @@ +--- +id: delete-project +title: Delete a project +sidebar_label: Delete Project +--- + +You can delete an Ory Network project by following these steps: + +1. Go to the [Ory Console](https://console.ory.sh). +2. Create a workspace API key for the workspace your project is in. +3. Copy the project ID from the project settings page. +4. Run the following cURL command: + ```bash + curl --location --request DELETE 'https://api.console.ory.sh/projects/${ORY_PROJECT_ID}' \ + --header 'Authorization: Bearer ${WORKSPACE_API_KEY}' \ + --header 'Accept: application/json' + ``` diff --git a/src/sidebar.js b/src/sidebar.js index f28a200b7..3ba70f30d 100644 --- a/src/sidebar.js +++ b/src/sidebar.js @@ -332,6 +332,7 @@ module.exports = { "guides/gitops", "guides/rate-limits", "guides/allowlist", + "guides/delete-project", ], }, { From 06cf0ef5c81a03076edfd94bc397768a3c2c72e2 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 13 Aug 2024 16:15:12 +0200 Subject: [PATCH 2/3] fix: add projects api guide --- docs/guides/delete-project.mdx | 17 --- docs/guides/manage-project-via-api.mdx | 201 +++++++++++++++++++++++++ src/sidebar.js | 2 +- 3 files changed, 202 insertions(+), 18 deletions(-) delete mode 100644 docs/guides/delete-project.mdx create mode 100644 docs/guides/manage-project-via-api.mdx diff --git a/docs/guides/delete-project.mdx b/docs/guides/delete-project.mdx deleted file mode 100644 index a848b6207..000000000 --- a/docs/guides/delete-project.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: delete-project -title: Delete a project -sidebar_label: Delete Project ---- - -You can delete an Ory Network project by following these steps: - -1. Go to the [Ory Console](https://console.ory.sh). -2. Create a workspace API key for the workspace your project is in. -3. Copy the project ID from the project settings page. -4. Run the following cURL command: - ```bash - curl --location --request DELETE 'https://api.console.ory.sh/projects/${ORY_PROJECT_ID}' \ - --header 'Authorization: Bearer ${WORKSPACE_API_KEY}' \ - --header 'Accept: application/json' - ``` diff --git a/docs/guides/manage-project-via-api.mdx b/docs/guides/manage-project-via-api.mdx new file mode 100644 index 000000000..150e45fff --- /dev/null +++ b/docs/guides/manage-project-via-api.mdx @@ -0,0 +1,201 @@ +--- +id: manage-project-via-api +title: Manage Ory Network projects through the API +sidebar_label: Project management via API +--- + +You can configure Ory Network projects using the [Ory Console](https://console.ory.sh/), as well as the +[Ory CLI](./cli/cli-basics) and in most cases those are the recommended tools. There are cases where you might want to use the API +directly, for example when managing a large number of projects or when exposing certain capabilities to your users in a B2B/B2B2C +scenario. +In this guide you will learn how to configure Ory Network projects using the API. + +To run this guide you need: + +- [curl](https://curl.se/) +- your **Ory Network project ID** and **Workspace ID** +- a **Workspace API Key** + +:::info + +To create a new Workspace API Key go to . + +::: + +### Usage + +Use the API Key in API calls, SDK calls, or command-line interactions. Ory Workspace API Keys have a `ory_wak_` prefix, which +helps to identify them in code. + +For example, when calling the API to get a project at /projects/:project_id, include the API Key in the Authorization header: + +```bash +GET /projects/$PROJECT_ID HTTP/1.1 +Host: api.console.ory.sh +Accept: application/json +# highlight-next-line +Authorization: Bearer ${WORKSPACE_API_KEY} +``` + +## Ory Network projects API snippets + +Open your favourite terminal and export the workspace API key and workspace ID. You can find the workspace ID in the +[overview](https://console.ory.sh/workspaces) or when you click into a workspace as part of the URL. + +```bash +export WORKSPACE_API_KEY= +export WORKSPACE_ID= +``` + +### List all projects + +List all your Ory Network projects, including stats like creation time, last update time and more using the listProjects API. + +```bash +curl --location --request GET 'https://api.console.ory.sh/projects' \ + --header "Accept: application/json" \ + --header "Authorization: Bearer ${WORKSPACE_API_KEY}" | jq +``` + +### Create a project + +Create a new Ory Network project through the API. You get the full configuration of the newly created project as response using +the createProject API. Here you can optionally specify the region and workspace the project should be created in. + +```bash +curl --location -v --request POST 'https://api.console.ory.sh/projects' \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer ${WORKSPACE_API_KEY}" \ + --data '{ + "name": "example", + "environment": "dev", + "home_region": "us-west", + "workspace_id": "'"${WORKSPACE_ID}"'" + }' | jq +``` + +Here the project will be created with the following settings: + +- `name`: example (can be freely chosen by you) +- `environment`: dev (can be "prod", "stage", or "dev") +- `home_region`: us-west +- `workspace_id`: your workspace id + +### Delete a project + +:::danger + +Use with extreme caution. This action can not be undone and will delete ALL your data. + +::: + +You can delete an Ory Network project by following these steps: + +```bash +export ORY_PROJECT_ID= + +curl --location -v --request DELETE "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}" \ + --header "Accept: application/json" \ + --header "Authorization: Bearer ${WORKSPACE_API_KEY}" +``` + +### Get a project + +To get the full configuration of your Ory Network project use the getProject API. + +```bash +export ORY_PROJECT_ID= + +curl --location --request GET "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}" \ + --header "Accept: application/json" \ + --header "Authorization: Bearer ${WORKSPACE_API_KEY}" | jq +``` + +### Update an Ory Network project Configuration + +You can use Workspace API keys to change a projects configuration through the API. + +In this example we add an Ory Action to the project. + +First, create a Jsonnet file that transforms the identity data from Ory to a format Segment understands: + +```json +function(ctx) { + userId: ctx.identity.id, + traits: { + email: ctx.identity.traits.email, + name: ctx.identity.traits.name, + newsletterConsent: ctx.identity.traits.consent.newsletter, + }, +} +``` + +Encode this Jsonnet snippet to Base64 and save it to the clipboard: + +`cat test.jsonnet | base64 | pbcopy` + +Define the Ory Action as a JSON Object. Remember to replace the example with your data: + +```bash +export ORY_PROJECT_ID= + +curl --location --request PATCH "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}" \ +-H "Authorization: Bearer ${WORKSPACE_API_KEY}" \ +-H "Content-Type: application/json" \ +-d '[ + { + "op": "add", + "path": "/services/identity/config/selfservice/flows/login/after/hooks/-", + "value": { + "hook": "web_hook", + "config": { + "url": "https://webhook.site/42a3f21-375b-4604-b4c7-15cc885ffa13", + "method": "POST", + "body": "base64://ZnVuY3Rpb24oY3R4KSB7CiAgdXNlcklkOiBjdHguaWRlbnRpdHkuaWQsCiAgdHJhaXRzOiB7CiAgICBlbWFpbDogY3R4LmlkZW50aXR5LnRyYWl0cy5lbWFpbCwKICAgIG5hbWU6IGN0eC5pZGVudGl0eS50cmFpdHMubmFtZSwKICAgIG5ld3NsZXR0ZXJDb25zZW50OiBjdHguaWRlbnRpdHkudHJhaXRzLmNvbnNlbnQubmV3c2xldHRlciwKICB9LAp9" + } + } + } +]' \ +| jq ".project.services.identity.config.selfservice.flows.login.after.hooks" +``` + +### List a project's API Tokens + +List all API Keys active using the listProjectApiKeys API, including creation dates, name and ID. Please note that you can not get +the value this way, it is only shown once upon creation of the API Key. + +```bash +curl --location --request GET "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}/tokens" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer ${WORKSPACE_API_KEY}" | jq +``` + +### Create project API token + +Use the createProjectApiKey API to create a new API Key. The output is similar to above, with the difference that you can see the +value now (this is the only time you see it!). + +```bash +curl --location --request POST "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}/tokens" \ +-d '{"name":"example"}' \ +-H "Content-Type: application/json" \ +-H "Authorization: Bearer ${WORKSPACE_API_KEY}" | jq +``` + +### Delete project API token + +In the same way you can also delete an API Key that is no longer used. You need the API Key ID to delete it with the +deleteProjectApiKey API. + +```bash +export ORY_PROJECT_API_KEY_ID= + +curl --location --request DELETE "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}/tokens/${ORY_PROJECT_API_KEY_ID}" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer ${WORKSPACE_API_KEY}" +``` + +### Create, update, delete organizations + +To learn more about how to use the Organizations or B2B SSO API, including examples, please refer to the guide in the +[Organizations and B2B Single Sign-On](kratos/organizations/organizations.mdx) documentation. diff --git a/src/sidebar.js b/src/sidebar.js index 3ba70f30d..024cff766 100644 --- a/src/sidebar.js +++ b/src/sidebar.js @@ -329,10 +329,10 @@ module.exports = { items: [ "guides/custom-domains", "guides/cors", + "guides/manage-project-via-api", "guides/gitops", "guides/rate-limits", "guides/allowlist", - "guides/delete-project", ], }, { From 664bea1593b6ec412bd3bc28a18d5e866b038017 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 13 Aug 2024 16:56:54 +0200 Subject: [PATCH 3/3] chore: remove -v flags --- docs/guides/manage-project-via-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/manage-project-via-api.mdx b/docs/guides/manage-project-via-api.mdx index 150e45fff..2f1167339 100644 --- a/docs/guides/manage-project-via-api.mdx +++ b/docs/guides/manage-project-via-api.mdx @@ -63,7 +63,7 @@ Create a new Ory Network project through the API. You get the full configuration the createProject API. Here you can optionally specify the region and workspace the project should be created in. ```bash -curl --location -v --request POST 'https://api.console.ory.sh/projects' \ +curl --location --request POST 'https://api.console.ory.sh/projects' \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${WORKSPACE_API_KEY}" \ --data '{ @@ -94,7 +94,7 @@ You can delete an Ory Network project by following these steps: ```bash export ORY_PROJECT_ID= -curl --location -v --request DELETE "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}" \ +curl --location --request DELETE "https://api.console.ory.sh/projects/${ORY_PROJECT_ID}" \ --header "Accept: application/json" \ --header "Authorization: Bearer ${WORKSPACE_API_KEY}" ```