-
Notifications
You must be signed in to change notification settings - Fork 193
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into cg-oidc-uris
- Loading branch information
Showing
106 changed files
with
2,736 additions
and
729 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,17 +6,72 @@ sidebar_position: 2 | |
| description: "Learn about access tokens and client credentials and scopes to get started with the Administration API." | ||
| --- | ||
|
|
||
| To access the API endpoint, you need an access token. Your client must send a header in each request: | ||
|
|
||
| `Authorization: Bearer <Token>` | ||
|
|
||
| For example, send a request using _curl_: | ||
| All Administration API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and pass it in each request. | ||
|
|
||
| ## Generating a token | ||
|
|
||
| 1. Create client credentials by clicking **Console > Organization > Administration API > Create new credentials**. | ||
| 2. Add permissions to this client for [the needed scopes](#client-credentials-and-scopes). | ||
| 3. Upon creating the client, capture the following values required to generate a token: | ||
| <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 --> | ||
| | Name | Environment variable name | Default value | | ||
| | ------------------------ | -------------------------------- | -------------------------------------------- | | ||
| | Client ID | `CAMUNDA_CONSOLE_CLIENT_ID` | - | | ||
| | Client Secret | `CAMUNDA_CONSOLE_CLIENT_SECRET` | - | | ||
| | Authorization Server URL | `CAMUNDA_OAUTH_URL` | `https://login.cloud.camunda.io/oauth/token` | | ||
| | Audience | `CAMUNDA_CONSOLE_OAUTH_AUDIENCE` | `api.cloud.camunda.io` | | ||
| <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 --> | ||
| :::tip | ||
| When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe. | ||
| ::: | ||
| 4. Execute an authentication request to the token issuer: | ||
| ```bash | ||
| curl --request POST ${CAMUNDA_OAUTH_URL} \ | ||
| --header 'Content-Type: application/x-www-form-urlencoded' \ | ||
| --data-urlencode 'grant_type=client_credentials' \ | ||
| --data-urlencode "audience=${CAMUNDA_CONSOLE_OAUTH_AUDIENCE}" \ | ||
| --data-urlencode "client_id=${CAMUNDA_CONSOLE_CLIENT_ID}" \ | ||
| --data-urlencode "client_secret=${CAMUNDA_CONSOLE_CLIENT_SECRET}" | ||
| ``` | ||
| 5. A successful authentication response looks like the following: | ||
| ```json | ||
| { | ||
| "access_token": "<TOKEN>", | ||
| "expires_in": 300, | ||
| "refresh_expires_in": 0, | ||
| "token_type": "Bearer", | ||
| "not-before-policy": 0 | ||
| } | ||
| ``` | ||
| 6. Capture the value of the `access_token` property and store it as your token. | ||
|
|
||
| ## Using a token | ||
|
|
||
| Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`. | ||
|
|
||
| For example, to call the Administration API's `/members` endpoint, send the following request: | ||
|
|
||
| ```shell | ||
| curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://api.cloud.camunda.io/clusters | ||
| curl --header "Authorization: Bearer ${TOKEN}" \ | ||
| https://api.cloud.camunda.io/members | ||
| ``` | ||
|
|
||
| A successful response would include [a list of organization members](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMembers). For example: | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "name": "User Userton", | ||
| "email": "[email protected]", | ||
| "roles": ["admin"], | ||
| "invitePending": false | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| For all requests, include the access token in the authorization header: `authorization:Bearer ${TOKEN}`. | ||
| ## Token expiration | ||
|
|
||
| Access tokens expire according to the `expires_in` property of a successful authentication response. After this duration, in seconds, you must request a new access token. | ||
|
|
||
| ## Client credentials and scopes | ||
|
|
||
|
|
@@ -40,25 +95,6 @@ A client can have one or multiple permissions from the following groups: | |
|
|
||
| The full API description can be found [here](https://console.cloud.camunda.io/customer-api/openapi/docs/#/). | ||
|
|
||
| :::note | ||
| After client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe. | ||
| ::: | ||
| ## Access token | ||
| Once you have your client credentials, you can retrieve an access token using the following command: | ||
| ```bash | ||
| curl --header "Content-Type: application/json" \ | ||
| --request POST \ | ||
| --data '{"grant_type":"client_credentials", "audience":"api.cloud.camunda.io", "client_id":"XXX", "client_secret":"YYY"}' \ | ||
| https://login.cloud.camunda.io/oauth/token | ||
| ``` | ||
| :::note | ||
| Access tokens have a validity period found in the access token. After this time, a new access token must be requested. | ||
| ::: | ||
| ## Rate limiting | ||
|
|
||
| The OAuth service rate limits about one request per second for all clients with the same source IP address. | ||
|
|
||
6 changes: 3 additions & 3 deletions
6
...e-sm-api/console-sm-api-authentication.md → ...i/administration-sm-api-authentication.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
18 changes: 18 additions & 0 deletions
18
docs/apis-tools/administration-sm-api/administration-sm-api-overview.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| --- | ||
| id: administration-sm-api-overview | ||
| title: "Overview" | ||
| sidebar_position: 1 | ||
| description: "Access the Administration API for Self-Managed." | ||
| --- | ||
|
|
||
| The Administration API for Self-Managed is a REST API and provides endpoints to get cluster data including installed apps and usage metrics. | ||
|
|
||
| ## API Explorer | ||
|
|
||
| See [the interactive Administration API Self-Managed Explorer][administration-api-explorer] for specifications, example requests and responses, and code samples of interacting with the Administration Self-Managed API. | ||
|
|
||
| ### Open API | ||
|
|
||
| An Open API UI is also available within a running instance of Console Self-Managed at `https://${base-url}/admin-api/openapi/docs`. | ||
|
|
||
| [administration-api-explorer]: ./specifications/sm-administration-api.info.mdx |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ | ||
|
|
||
| module.exports = { | ||
| "Administration API (Self-Managed)": [ | ||
| "apis-tools/administration-sm-api/administration-sm-api-overview", | ||
| "apis-tools/administration-sm-api/administration-sm-api-authentication", | ||
| { | ||
| Specifications: require("./specifications/sidebar.js"), | ||
| }, | ||
| ], | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.