diff --git a/docs/dev/reference/apis/billing-client.md b/docs/dev/reference/apis/billing-client.md index 422c2dc0cb..d0d6f026da 100644 --- a/docs/dev/reference/apis/billing-client.md +++ b/docs/dev/reference/apis/billing-client.md @@ -33,7 +33,7 @@ You will also need an API key and API key ID to authenticate your session. Your API key needs to have [Org owner permissions](/manage/manage/rbac/#organization-settings-and-roles) to use the billing client API. To get an API key (and corresponding ID), you have two options: -- [Create an API key using the Viam app](/cloud/rbac/#add-an-api-key) +- [Create an API key using the Viam app](/operate/control/api-keys/#add-an-api-key) - [Create an API key using the Viam CLI](/dev/tools/cli/#create-an-organization-api-key) The following example instantiates a `ViamClient`, authenticating with an API key, and then instantiates a `BillingClient`: diff --git a/docs/dev/reference/apis/data-client.md b/docs/dev/reference/apis/data-client.md index ff09a1704b..d5eed3dd42 100644 --- a/docs/dev/reference/apis/data-client.md +++ b/docs/dev/reference/apis/data-client.md @@ -49,7 +49,7 @@ To use the Viam data client API, you first need to instantiate a [`ViamClient`]( You will also need an API key and API key ID to authenticate your session. To get an API key (and corresponding ID), you have two options: -- [Create an API key using the Viam app](/cloud/rbac/#add-an-api-key) +- [Create an API key using the Viam app](/operate/control/api-keys/#add-an-api-key) - [Create an API key using the Viam CLI](/dev/tools/cli/#create-an-organization-api-key) The following example instantiates a `ViamClient`, authenticating with an API key, and then instantiates a `DataClient`: diff --git a/docs/manage/manage/access.md b/docs/manage/manage/access.md index a9dd0bba17..2c4380e857 100644 --- a/docs/manage/manage/access.md +++ b/docs/manage/manage/access.md @@ -98,13 +98,6 @@ You can also remove the user by clicking on **Remove user**. You can remove any organization except the primary owner from the shared list by clicking the **X** to the right of the location in the shared list. -## Rotate an API key - -If you ever need to rotate an API key, click on the **Generate Key** button on the organization setting page to generate a new key. - -Viam supports flexible key rotation with up to two keys in use at one time. -After generating a new secret key, update all references to the key in your code as soon as possible and then remove the old key. - ## Collaborate safely When you or your collaborators change the configuration of a machine or a group of machines in the Viam app, `viam-server` automatically synchronizes the configuration and updates the running resources within 15 seconds. diff --git a/docs/operate/control/api-keys.md b/docs/operate/control/api-keys.md new file mode 100644 index 0000000000..e432511cb0 --- /dev/null +++ b/docs/operate/control/api-keys.md @@ -0,0 +1,46 @@ +--- +title: "API keys" +linkTitle: "API keys" +weight: 50 +layout: "docs" +type: "docs" +description: "Run control logic on a machine." +images: ["/general/code.png"] +date: "2024-01-13" +--- + +API keys grant access to organizations, locations, and machines. + +To view all API keys in use for your organization and the locations and machines inside it, click on the organization dropdown in the top navigation bar and click on **Settings**. + +{{}} + +## Add an API key + +On your organization's page, click **Generate key** to generate a new key. +Optionally, give the key a name. +Click on the **Resource** menu and choose what organization, location, or machine you want the key to grant access to. +If you select organization, your key grants access to all locations and machines contained within that organization. +If you select location, your key grants access to all of the machines contained within that location. + +For **Role**, assign either an **Owner** or **Operator** role. +See [Permissions](/manage/manage/rbac/) for information about the privilege each role entails at each resource level. + +## Change an API key's access + +To edit an API key, click on **Show details** in the key's row of the key table's **Resources** column. + +{{}} + +To edit the role, click on the dropdown menu next to the role and select **Owner** or **Operator**. +See [Permissions](/manage/manage/rbac/) for information about the privilege each role entails at each resource level. + +To change the entities it is able to access, click **+ Grant additional access**. +Select which organization, location, or machine you want the key to grant access to. +Click **Choose** to confirm your selection. + +## Rotate an API key + +If you ever need to rotate an API key, click on the **Generate Key** button on the organization setting page to generate a new key. + +Viam supports flexible key rotation with up to two keys in use at one time. After generating a new secret key, update all references to the key in your code as soon as possible and then remove the old key. diff --git a/static/include/app/apis/generated/app.md b/static/include/app/apis/generated/app.md index 85d21853fc..2e9aff1061 100644 --- a/static/include/app/apis/generated/app.md +++ b/static/include/app/apis/generated/app.md @@ -803,7 +803,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### GetRobotAPIKeys -Gets the [API keys](/cloud/rbac/#api-keys) for the machine. +Gets the [API keys](/operate/control/api-keys/) for the machine. {{< tabs >}} {{% tab name="Python" %}} @@ -2140,7 +2140,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### CreateKey -Create a new [API key](/cloud/rbac/#api-keys). +Create a new [API key](/operate/control/api-keys/). {{< tabs >}} {{% tab name="Python" %}} @@ -2184,7 +2184,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### DeleteKey -Delete an [API key](/cloud/rbac/#api-keys). +Delete an [API key](/operate/control/api-keys/). {{< tabs >}} {{% tab name="Python" %}} @@ -2210,7 +2210,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### RotateKey -Rotate an [API key](/manage/manage/access/#rotate-an-api-key). +Rotate an [API key](/operate/control/api-keys/#rotate-an-api-key). {{< tabs >}} {{% tab name="Python" %}} diff --git a/static/include/app/apis/overrides/protos/app.GetRobotApiKeys.md b/static/include/app/apis/overrides/protos/app.GetRobotApiKeys.md index d337e30720..66ed6b486e 100644 --- a/static/include/app/apis/overrides/protos/app.GetRobotApiKeys.md +++ b/static/include/app/apis/overrides/protos/app.GetRobotApiKeys.md @@ -1 +1 @@ -Gets the [API keys](/cloud/rbac/#api-keys) for the machine. +Gets the [API keys](/operate/control/api-keys/) for the machine. diff --git a/static/include/app/apis/overrides/protos/app.RotateKey.md b/static/include/app/apis/overrides/protos/app.RotateKey.md index 08daca68ff..f6899fb214 100644 --- a/static/include/app/apis/overrides/protos/app.RotateKey.md +++ b/static/include/app/apis/overrides/protos/app.RotateKey.md @@ -1 +1 @@ -Rotate an [API key](/manage/manage/access/#rotate-an-api-key). +Rotate an [API key](/operate/control/api-keys/#rotate-an-api-key). diff --git a/static/include/program/authenticate.md b/static/include/program/authenticate.md index f73c50ec0b..b3b9ad29de 100644 --- a/static/include/program/authenticate.md +++ b/static/include/program/authenticate.md @@ -4,7 +4,7 @@ To authenticate yourself to your machine, you need - To authenticate, [use a machine part API key](/cloud/machines/#api-keys) or [an API key](/dev/tools/cli/#authenticate) with access to the machine. + To authenticate, [use a machine part API key](/operate/control/api-keys/) or [an API key](/dev/tools/cli/#authenticate) with access to the machine. Copy and paste the API key ID and the API key into your environment variables or directly into the code: {{< tabs >}}