docs: remove RA references (#910)

Signed-off-by: Miguel Martinez Trivino <[email protected]>

Author: migmartri

docs/docs/getting-started/attestation-crafting.md

@@ -10,7 +10,7 @@ title: Attestation Crafting
 
 ## Introduction
 
-In the previous section, we created a workflow definition, a contract and a robot account in the control plane. Next, we'll perform an attestation crafting example using Chainloop.
+In the previous section, we created a workflow definition, a contract and an API Token in the control plane. Next, we'll perform an attestation crafting example using Chainloop.
 
 The lifecycle of a crafting process has the following stages: `init`, `add`, `push` or `reset`. As you can see, it mimics the workflow of a commonly used version control tool, and this is not by coincidence. Chainloop wants to make sure that the tooling feels familiar to developers and that no security jargon leaks into this stage of the process. For a developer, creating an attestation must be as simple as initializing it, adding materials to it and pushing it.
 
@@ -23,21 +23,21 @@ During this stage, the crafting tool will contact the control plane to
 - Signal the intent of starting an attestation.
 - Retrieve the associated workflow contract.
 - If the contract has a specified runner context type, check that we are compliant with it.
-- Initialize environment variables explicitly stated in the contract.
-
-:::note
-In the future, during this initialization stage, we will also retrieve ephemeral signing keys for keyless signing/verification
-:::
+- Initialize environment variables, explicitly stated in the contract and other contextual information.
 
 #### attestation add
 
-Add the **materials required by the contract**, i.e artifact, OCI image ref, SBOM.
+Add the **materials required by the contract** and any other additional pieces of evidence, i.e artifact, OCI image ref, SBOM.
 
 The `add` command knows how to handle each kind of material transparently to the user.
 
-- STRING kinds will be injected as is.
+For example
+
 - ARTIFACT kinds will be uploaded to your artifact registry and referenced by their content digest.
 - CONTAINER_IMAGE kinds will be resolved to obtain their repository digests using the local authentication keychain.
+- SBOM_CYCLONEDX_JSON will validate the right SBOM format and upload it to the artifact registry.
+
+For a complete list of available material types, see the [reference](/reference/operator/contract#material-schema).
 
 #### attestation push
 
@@ -47,7 +47,7 @@ This stage will take the current crafting state, validate that it has all the re
 - Push it to the control plane for storage
 
 :::note
-Chainlooop leverages Cosign for signing and verifying, so it supports any of its key providers.
+Chainloop leverages Cosign for signing and verifying, so it supports any of its key providers.
 Currently, local file-based `cosign private key` and GCP, AWS, Azure and Hashicorp Vault KMS are supported.
 
 In future releases this will not be needed since we will rely on keyless signing and verification.
@@ -63,31 +63,31 @@ See the state of the current crafting process.
 
 ## Crafting our first attestation locally
 
-To create an attestation two things are required, the Chainloop crafting tool and a robot account.
+To create an attestation two things are required, the Chainloop crafting tool and an [API Token](/reference/operator/api-tokens).
 
 The crafting tool is currently bundled within Chainloop command line tool. To install it just follow the [installation](installation) instructions.
 
-The robot account was created during the [previous step](./workflow-definition#robot-account-creation) and it's required during all the stages of the crafting process. It can be provided via the `--token` flag or the `$CHAINLOOP_TOKEN` environment variable.
-
-### Initialization
+The API Token was created during the [previous step](./workflow-definition#api-token-creation) and it's required during all the stages of the crafting process. It can be provided via the `--token` flag or the `$CHAINLOOP_TOKEN` environment variable.
 
 ```bash
 $ export CHAINLOOP_TOKEN=deadbeef
 ```
 
+### Initialization
+
 #### Options
 
 `chainloop attestation init` supports the following options
 
-- `--token` token provided by the SecOps team. Alternatively, you can set the `CHAINLOOP_TOKEN` environment variable.
+- `--token` token provided by the SecOps team. Alternatively, you can set the `CHAINLOOP_TOKEN` environment variable (required).
+- `--name` name of the workflow to run the attestation (required).
 - `--revision` of the contract (default: `latest`).
-- `--workflow-name` name of the workflow to run the attestation. This is ignored when authentication is based on robot account and needed for api tokens.
 - `--dry-run`; do not store the attestation in the Control plane, and do not fail if the runner context or required env variables can not be resolved. Useful for development (default: `false`).
 
 To initialize a new crafting process just run `attestation init` and the system will retrieve the latest version (if no specific revision is set via the `--revision` flag) of the contract.
 
 ```bash
-$ chainloop attestation init --dry-run
+$ chainloop attestation init --name build-and-test
 
 INF Attestation initialized! now you can check its status or add materials to it
 ┌───────────────────┬──────────────────────────────────────┐
@@ -191,14 +191,21 @@ $ chainloop attestation status --full
 ### Encode, sign and push attestation
 
 :::note
-Chainlooop leverages Cosign for signing and verifying, so it supports any of its key providers.
+Chainloop leverages Cosign for signing and verifying, so it supports any of its key providers.
 Currently, local file-based `cosign private key` and GCP, AWS, Azure and Hashicorp Vault KMS are supported.
 In future releases this will not be needed since we will rely on keyless signing and verification.
 :::
 
-Since all the required materials have been attached, a **signed in-toto statement can now be generated and sent for storage**. This example uses AWS KMS for signing:
+Since all the required materials have been attached, a **signed in-toto statement can now be generated and sent for storage**. 
+
+```bash
+# Sign and push using a local private key
+$ export CHAINLOOP_SIGNING_PASSWORD="private key passphrase"
+$ chainloop attestation push --key cosign-private.key
+```
 
 ```bash
+# or, as additional example, using KMS
 $ chainloop attestation push --key awskms:///arn:aws:kms:us-east-1:1234567890:key/12345678-a843-43e1-8c5b-1234567890
 ```
 
@@ -216,7 +223,6 @@ INF Attestation pushed!
       }
    ]
 }
-
 ```
 
 ## CI integration
@@ -242,10 +248,11 @@ jobs:
     env:
       # highlight-start
       # Version of Chainloop to install
-      CHAINLOOP_VERSION: 0.86.0
-      # Export robot-account env variable
+      CHAINLOOP_VERSION: 0.91.1
       # Used by the CLI to authenticate with the control plane
-      CHAINLOOP_ROBOT_ACCOUNT: ${{ secrets.CHAINLOOP_WF_RELEASE }}
+      CHAINLOOP_TOKEN: ${{ secrets.CHAINLOOP_WF_RELEASE }}
+      # The name of the workflow registered in Chainloop control plane
+      CHAINLOOP_WORKFLOW_NAME: build-and-test
       # highlight-end
     name: "Release CLI and container images"
     runs-on: ubuntu-latest
@@ -268,7 +275,7 @@ jobs:
       # highlight-start
       - name: Initialize Attestation
         run: |
-          chainloop attestation init --contract-revision 1
+          chainloop attestation init --name $CHAINLOOP_WORKFLOW_NAME --contract-revision 1
       # highlight-end
       - name: Set up Go
         uses: actions/setup-go@v3
@@ -322,7 +329,7 @@ jobs:
         if: ${{ success() }}
         run: |
           chainloop attestation status --full
-          # Note that these commands are using CHAINLOOP_ROBOT_ACCOUNT env variable to authenticate
+          # Note that these commands are using CHAINLOOP_TOKEN env variable to authenticate
           chainloop attestation push --key env://CHAINLOOP_SIGNING_KEY
         env:
           CHAINLOOP_SIGNING_KEY: ${{ secrets.COSIGN_KEY }}

docs/docs/getting-started/workflow-definition.mdx

@@ -22,9 +22,9 @@ A workflow represents the identity of any automation, any CI/CD workflow you wan
 
 <WorkflowContractIntro />
 
-### Robot Accounts
+### Chainloop API Token
 
-A robot account is a long-lasting, though revokable, **secret token associated with a Workflow**. It's meant to be used in the target CI/CD pipeline during the attestation process. This token along with the crafting CLI are the only two things development/Apps teams need for the integration.
+A [Chainloop API Token](/reference/operator/api-tokens) is a long-lasting, though revokable, **secret token associated with a Chainloop organization**. It's meant to be used in the target CI/CD pipeline during the attestation process and/or for unatended operations with the controlplane. This token along with the crafting CLI are the only two things development teams need to perform attestations.
 
 ## Workflow and Contract creation
 
@@ -34,7 +34,7 @@ To achieve that, we will need to
 
 - Create a new Workflow Contract (optional)
 - Create a Workflow associated with a new or existing Contract
-- Create a Robot account for that Workflow so the integration can happen in the CI.
+- Create an API Token for the CI/CD integration
 
 ### Workflow Create
 
@@ -146,32 +146,31 @@ $ chainloop workflow contract update \
 We could have reached the same result by first creating the contract via `chainloop workflow contract create -f ...` and then attaching it during workflow creation `chainloop workflow create ... --contract deadbeef`
 :::
 
-### Robot Account creation
+### API Token Creation
 
-The final step is to create a robot account that will be shared with the development team so they can start the integration.
+The final step is to create an API Token that will be shared with the development team so they can start the integration.
 
 :::note
 
-- Robot accounts are attached to a single workflow. If you create another workflow, another robot account must be created.
-- You can have more than one robot account associated with a workflow.
-- Accounts can be revoked via `chainloop workflow robot-account revoke` command
+- API Tokens are attached to a single organization and can be used to perform attestations in multiple workflows.
+- You can have multiple API Tokens per organization
+- Tokens can be revoked via `chainloop org api-token revoke` command
 
 :::
 
 ```bash
-$ chainloop workflow robot-account create \
-    --workflow 2d289d33-8241-47b7-9ea2-8bd8b7c126f8 \
-    --name prod-ci
+$ chainloop org api-token create --name prod-ci
 
-┌──────────────────────────────────────┬─────────┬──────────────────────────────────────┬─────────────────────┬────────────┐
-│ ID                                   │ NAME    │ WORKFLOW ID                          │ CREATED AT          │ REVOKED AT │
-├──────────────────────────────────────┼─────────┼──────────────────────────────────────┼─────────────────────┼────────────┤
-│ 4f2376fa-48c8-4e46-a921-977ec44486a9 │ prod-ci │ 2d289d33-8241-47b7-9ea2-8bd8b7c126f8 │ 01 Nov 22 23:43 UTC │            │
-└──────────────────────────────────────┴─────────┴──────────────────────────────────────┴─────────────────────┴────────────┘
+┌──────────────────────────────────────┬─────────┬─────────────┬─────────────────────┬────────────┬────────────┐
+│ ID                                   │ NAME    │ DESCRIPTION │ CREATED AT          │ EXPIRES AT │ REVOKED AT │
+├──────────────────────────────────────┼─────────┼─────────────┼─────────────────────┼────────────┼────────────┤
+│ 7016d5ad-6d2b-4da4-b657-4ad1ddcb4469 │ prod-ci │             │ 05 Jun 24 14:56 UTC │            │            │
+└──────────────────────────────────────┴─────────┴─────────────┴─────────────────────┴────────────┴────────────┘
 
-Save the following token since it will not printed again:
+Save the following token since it will not printed again: 
+
+ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.REDACTED.GzTiR2r8YuccAmn-eZjCMNTSY5MU2gcRGNzu5rBhl80
 
- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.REDACTED.lXdvZusJgHyeHDl39RGPNxxrmTUZBN0_QAbJU5ZVxR8
 ```
 
 We have everything we need to integrate our CI with Chainloop!

docs/docs/guides/dagger/README.md

@@ -17,7 +17,7 @@ Daggerized version of [Chainloop](https://docs.chainloop.dev) that can be used t
 
 
 - This module requires existing familiarity with Chainloop and its attestation process. Please refer to [this guide](https://docs.chainloop.dev/getting-started/attestation-crafting) to learn more.
-- You need a `token` (aka workflow robot account) [previously generated](https://docs.chainloop.dev/getting-started/workflow-definition#robot-account-creation) by your Chainloop administrator.
+- You need an `API Token` [previously generated](https://docs.chainloop.dev/getting-started/workflow-definition#api-token-creation) by your Chainloop administrator.
 
 ## Attestation Crafting
 

docs/docs/guides/dependency-track/dependency-track.mdx

@@ -43,9 +43,9 @@ There are two steps involved to enable this integration:
 
 ### Prerequisites
 
-**Dependency-Track API token**
+**Dependency-Track API Token**
 
-An API token is required for the Chainloop instance to communicate securely with DependencyTrack. The required permissions are `BOM_UPLOAD`, `VIEW_PORTFOLIO` (to validate that the provided project ID exists) and optionally `PROJECT_CREATION_UPLOAD` if `project-auto-creation` is enabled, more on that later.
+An API Token is required for the Chainloop instance to communicate securely with DependencyTrack. The required permissions are `BOM_UPLOAD`, `VIEW_PORTFOLIO` (to validate that the provided project ID exists) and optionally `PROJECT_CREATION_UPLOAD` if `project-auto-creation` is enabled, more on that later.
 
 The API Key can be created by going to Settings -> Access Management -> Teams -> Select (or create) a Team -> Set permissions -> Copy API key
 

docs/docs/guides/github-releases/github-releases.md

@@ -52,7 +52,7 @@ jobs:
 This workflow will trigger every time a new release is published in your repository. It will collect all the assets from the release page and attest them using Chainloop. The attestation will be stored in the workflow you specify in the `workflow_name` field.
 There are some parameters that you need to provide:
 - `workflow_name`: The name of the workflow in Chainloop where the attestation will be stored.
-- `api_token`: The Chainloop API token to authenticate with the Chainloop API.
+- `api_token`: The Chainloop API Token to authenticate with the Chainloop API.
 - `cosign_key`: The path to the `cosign` key file.
 - `cosign_password`: The passphrase for the `cosign` key.
 

docs/docs/guides/sbom-management/sbom-management.mdx

@@ -30,9 +30,9 @@ In the first part, we explain how to:
 This guide makes the following assumptions:
 * You have Chainloop CLI already installed, and you have already authenticated to the Chainloop control plane. Please check [this CLI installation guide](/getting-started/installation) if you don't.
 * You have already added your OCI registry, where all artifacts, metadata, and attestations will be stored. Please learn more about how to do it in [the Account Setup section](/getting-started/setup).
-* You have a Chainloop Workflow, default empty Contract, and Robot Account created as explained in [this document](/getting-started/workflow-definition).
+* You have a Chainloop Workflow, and an API Token created as explained in [this document](/getting-started/workflow-definition).
 * You have a Github Action created for your project in your GitHub repository, which is connected to your Chainloop workflow. The Chainloop Integration Demo Action is a good example. You can check it out [here](https://github.com/chainloop-dev/integration-demo/blob/main/chainloop-demo/github-workflow/release.v1.yaml).
-* Your Chainloop Robot Account Token is set locally and in your GitHub project as the `CHAINLOOP_ROBOT_ACCOUNT` environment variable. The Chainloop CLI uses this token to authenticate with our Control Plane.
+* Your Chainloop API Token is set locally and in your GitHub project as the `CHAINLOOP_TOKEN` environment variable. The Chainloop CLI uses this token to authenticate with our Control Plane.
 * Your Private Key and Private Key Password are exposed locally and in your Github project as the following environment variables. We use this key to sign in-toto attestations for your artifacts, such as SBOMs.
   * `CHAINLOOP_SIGNING_KEY`
   * `CHAINLOOP_SIGNING_PASSWORD`
@@ -79,7 +79,8 @@ Although the workflow run process can be complex, we will highlight the three mo
 ### Initializing an attestation
 Before adding and sending SBOMs to Chainloop, initiating the attestation process is necessary.
 ```bash
-chainloop attestation init
+# --name sbom-cdx is an example of the name of the workflow registered in Chainloop's control plane
+chainloop attestation init --name sbom-cdx
 ```
 ### Generating SBOMs
 Generate SBOM with Syft. Running this command locally will probably generate an empty SBOM, but it should be good enough in our example.

docs/docs/quickstart.md

@@ -28,13 +28,13 @@ In this quickstart, we will install Chainloop and make our first attestation:
     for a complete explanation of Workflows and Contracts.
     You might also want to check our [contract reference](/reference/operator/contract).
 
-4. Create API token to perform the attestation process:
+4. Create API Token to perform the attestation process:
     ```bash
     export CHAINLOOP_TOKEN=$(chainloop org api-token create --name test-api-token -o json | jq -r ".[].jwt")
     ```
     CHAINLOOP_TOKEN environment variable is commonly used from CI/CD scenarios, where a personal token is not available.
     Tokens have narrower permissions, ensuring that they can only perform the operations they are granted to.
-    More information in [API tokens](/reference/operator/api-tokens#api-tokens).
+    More information in [API Tokens](/reference/operator/api-tokens#api-tokens).
 
 5. Perform an attestation: