diff --git a/docs/admin/authentication/applications.md b/docs/admin/authentication/applications.md index 1df0ad595b..f91ef5dc44 100644 --- a/docs/admin/authentication/applications.md +++ b/docs/admin/authentication/applications.md @@ -1,14 +1,13 @@ -This article explains the procedure to manage applications and it’s permissions. +This article explains the procedure to manage your organization's applications. -Applications are used for API integrations with Run:ai. An application contains a secret key. Using the secret key you can obtain a token and use it within subsequent API calls. +Applications are used for API integrations with Run:ai. An application contains a client ID and a client secret. With the client credentials, you can obtain a token as detailed in [API authentication](../developer/rest-auth.md) and use it within subsequent API calls. -Applications are managed locally and assigned with Access Rules to manage its permissions. - -For example, application **ci-pipeline-prod** assigned with a **Researcher** role in **Cluster: A**. +Applications are assigned with Access Rules to manage permissions. +For example, application **ci-pipeline-prod** is assigned with a **Researcher** role in **Cluster: A**. ## Applications table -The Applications table can be found under **Tools & Settings** in the Run:ai platform. +The Applications table can be found under **Access** in the Run:ai platform. The Applications table provides a list of all the applications defined in the platform, and allows you to manage them. @@ -20,13 +19,14 @@ The Applications table consists of the following columns: | Column | Description | | :---- | :---- | | Application | The name of the application | -| Status | The status of the application | +| Client ID | The client ID of the application | | Access rule(s) | The access rules assigned to the application | | Last login | The timestamp for the last time the user signed in | | Created by | The user who created the application | | Creation time | The timestamp for when the application was created | | Last updated | The last time the application was updated | + ### Customizing the table view * Filter \- Click ADD FILTER, select the column to filter by, and enter the filter values @@ -40,27 +40,25 @@ The Applications table consists of the following columns: To create an application: 1. Click **\+NEW APPLICATION** -1. Enter the application’s **Name** -1. Click **CREATE** -1. Copy the credentials and store it securely: - * **Application name** - * **Secret key** -1. Click **DONE** +2. Enter the application’s **name** +3. Click **CREATE** +4. Copy the **Client ID** and **Client secret** and store them securely +5. Click **DONE** !!!Note - The secret key is visible only at the time of creation, it cannot be recovered but can be regenerated. + The client secret is visible only at the time of creation. It cannot be recovered but can be regenerated. ## Adding an access rule to an application To create an access rule: 1. Select the application you want to add an access rule for -1. Click **ACCESS RULES** -1. Click **\+ACCESS RULE** -1. Select a role -1. Select a scope -1. Click **SAVE RULE** -1. Click **CLOSE** +2. Click **ACCESS RULES** +3. Click **\+ACCESS RULE** +4. Select a role +5. Select a scope +6. Click **SAVE RULE** +7. Click **CLOSE** ## Deleting an access rule from an application @@ -72,26 +70,25 @@ To delete an access rule: 1. Click on the trash icon 1. Click **CLOSE** -## Regenerating key +## Regenerating client secret -To regenerate an application’s key: +To regenerate a client secret: -1. Select the application you want to regenerate it’s secret key -1. Click **REGENERATE KEY** -1. Click **REGENERATE** -1. Review the user’s credentials and store it securely: - * **Application** name - * **Secret key** -1. Click **DONE** +1. Locate the application you want to regenerate its client secret +2. Click **REGENERATE CLIENT SECRET** +3. Click **REGENERATE** +4. Copy the **New client secret** and store it securely +5. Click **DONE** !!!Warning - Regenerating an application key revokes its previous key. + Regenerating a client secret revokes the previous one. + ## Deleting an application 1. Select the application you want to delete 1. Click **DELETE** -1. On the dialog, click **DELETE** to confirm the deletion +1. On the dialog, click **DELETE** to confirm ## Using API diff --git a/docs/admin/authentication/img/appstable.png b/docs/admin/authentication/img/appstable.png index a89540d4b1..00e705b995 100644 Binary files a/docs/admin/authentication/img/appstable.png and b/docs/admin/authentication/img/appstable.png differ diff --git a/docs/developer/rest-auth.md b/docs/developer/rest-auth.md index 97c8452d50..25803cde74 100644 --- a/docs/developer/rest-auth.md +++ b/docs/developer/rest-auth.md @@ -3,35 +3,23 @@ The following document explains how to authenticate with Run:ai APIs. -Run:ai APIs are accessed using *bearer tokens*. A token can be obtained in several ways: +Run:ai APIs are accessed using *bearer tokens*. A token can be obtained by creating an **Application** through the Run:ai user interface. -* When logging into the Run:ai user interface, you enter an email and password (or authenticated via single sign-on) which are used to obtain a token. -* When using the Run:ai command-line, you use a Kubernetes profile and are authenticated by pre-running `runai login` (or oc login with OpenShift). The command attaches a token to the profile and allows you access to Run:ai functionality. -* When using Run:ai APIs, you need to create an **Application** through the Run:ai user interface. The Application is created with specific roles and contains a *secret*. Using the secret you can obtain a token and use it within subsequent API calls. +An application contains a client ID and a client secret. With the client credentials you can obtain a token and use it within subsequent API calls. -## Create a Client Application +* To create applications for your organization, see [Applications](../admin/authentication/applications.md). +* To create your own user applications, see [User Applications](../Researcher/best-practices/user-applications.md). -* Open the Run:ai Run:ai User Interface. -* Go to `Settings & Tools`, `Application` and create a new Application. -* Copy the `` and `` to be used below - - -### Access rules for the Application - -For you API requests to be accepted, you will need to set access rules for the application. -To assign roles to an application, see [Create or Delete rules](../admin/authentication/accessrules.md). - -Use the [Roles](../admin/authentication/roles.md#roles-in-runai) table to assign the correct roles to the application. ## Request an API Token -Use the above parameters to get a temporary token to access Run:ai as follows. +Use the client credentials created to get a temporary token to access Run:ai as follows. ### Example command to get an API token -Replace `` below with: +Replace `` below with: - * For SaaS installations use `.run.ai` + * For SaaS installations, use `.run.ai` * For self-hosted use the Run:ai user interface URL. @@ -42,9 +30,9 @@ Replace `` below with: --header 'Accept: */*' \ --header 'Content-Type: application/json' \ --data-raw '{ - "grantType":"app_token", - "AppId":"", - "AppSecret" : "" + "grantType":"client_credentials", + "clientId":"", + "clientSecret" : "" }' ``` @@ -52,15 +40,15 @@ Replace `` below with: ``` python import requests import json - reqUrl = "https://cp-590d-run-13764-kc-upgrade.runailabs.com/api/v1/token" + reqUrl = "https:///api/v1/token" headersList = { "Accept": "*/*", "Content-Type": "application/json" } payload = json.dumps({ - "grantType":"app_token", - "AppId":"", - "AppSecret" : "" + "grantType":"client_credentials", + "clientId":"", + "clientSecret" : "" }) response = requests.request("POST", reqUrl, data=payload, headers=headersList) print(response.text) diff --git a/docs/developer/user-applications.md b/docs/developer/user-applications.md new file mode 100644 index 0000000000..70f1509ca6 --- /dev/null +++ b/docs/developer/user-applications.md @@ -0,0 +1,47 @@ +# User Applications + +This article explains the procedure to create your own user applications. + +Applications are used for API integrations with Run:ai. An application contains a client ID and a client secret. With the client credentials, you can obtain a token as detailed in [API authentication](../developer/rest-auth.md) and use it within subsequent API calls. + +## Creating Applications + +To create an application: + +1. Click the user icon, then select Settings +2. Click **+APPLICATION** +3. Enter the application’s **name** +4. Click **CREATE** +5. Copy the **Client ID** and **Client secret** and store securely +6. Click **DONE** + +You can create up to 20 user applications. + +!!!Note + The client secret is visible only at the time of creation. It cannot be recovered but can be regenerated. + + +## Regenerating client secret + +To regenerate a client secret: + +1. Locate the application you want to regenerate its client secret +2. Click **Regenerate client secret** +3. Click **REGENERATE** +4. Copy the **New client secret** and store it securely +5. Click **DONE** + +!!!Warning + Regenerating a client secret revokes the previous one. + +## Deleting an application + +1. Locate the application you want to delete +2. Click on the trash icon +3. On the dialog, click **DELETE** to confirm + +## Using API + +Go to the [User Applications](https://api-docs.run.ai/#tag/User-Applications) API reference to view the available actions + + diff --git a/mkdocs.yml b/mkdocs.yml index e0ed14256e..08d73e6c75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -424,6 +424,7 @@ nav: - 'Use Cases' : 'Researcher/use-cases.md' - 'Developer' : - 'Overview' : 'developer/overview-developer.md' + - 'User Applications' : 'developer/user-applications.md' - 'API Authentication' : 'developer/rest-auth.md' - 'REST API' : 'developer/admin-rest-api/overview.md' - 'Cluster API (Deprecated)' :