From 430a76e9b0fad702aa8251ae4c61e888eca8801e Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 15 Apr 2026 09:51:41 -0700 Subject: [PATCH 1/2] docs: add machine accounts documentation Adds two pages covering the machine accounts feature: - platform/machine-accounts.mdx: overview, creating accounts, managing keys, assigning roles, and disabling/deleting - platform/machine-account-credentials.mdx: using credentials with datumctl, GitHub Actions, Kubernetes, and env vars Updates docs.json to include both pages in the Platform nav group. --- docs.json | 2 + platform/machine-account-credentials.mdx | 88 ++++++++++++++++++++++++ platform/machine-accounts.mdx | 48 +++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 platform/machine-account-credentials.mdx create mode 100644 platform/machine-accounts.mdx diff --git a/docs.json b/docs.json index d60812f..6db527d 100644 --- a/docs.json +++ b/docs.json @@ -76,6 +76,8 @@ "platform/metrics-export", "platform/activity-logs", "platform/secrets", + "platform/machine-accounts", + "platform/machine-account-credentials", "platform/locations" ] }, diff --git a/platform/machine-account-credentials.mdx b/platform/machine-account-credentials.mdx new file mode 100644 index 0000000..8b95c04 --- /dev/null +++ b/platform/machine-account-credentials.mdx @@ -0,0 +1,88 @@ +--- +title: "Using Machine Account Credentials" +description: "Authenticate CI/CD pipelines, Kubernetes workloads, and backend services using machine account credentials" +--- + +After [creating a machine account](/platform/machine-accounts), you'll have a credentials file or a key pair to use for authentication. This page covers how to use those credentials in common environments. + +## Credentials file format + +When you create a datum-managed key, Datum returns a JSON credentials file: + +```json +{ + "type": "datum_machine_account", + "client_id": "...", + "private_key_id": "...", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...", + "client_email": "my-account@my-namespace.my-project.iam.datum.net" +} +``` + +This file is the only artifact you need to authenticate. Treat it like a password — store it in a secrets manager, never commit it to source control. + +## datumctl + +Point `datumctl` at the credentials file using the `--credentials-file` flag: + +```text +datumctl auth login --credentials-file /path/to/credentials.json +``` + +Or set the environment variable so all subsequent commands pick it up automatically: + +```text +export DATUM_CREDENTIALS_FILE=/path/to/credentials.json +datumctl organizations list +``` + +## GitHub Actions + +Store the contents of the credentials file as a repository or organization secret (e.g. `DATUM_CREDENTIALS`), then write it to disk in your workflow: + +```yaml +- name: Authenticate with Datum + run: echo "$DATUM_CREDENTIALS" > /tmp/datum-credentials.json + env: + DATUM_CREDENTIALS: ${{ secrets.DATUM_CREDENTIALS }} + +- name: Run datumctl + run: datumctl organizations list + env: + DATUM_CREDENTIALS_FILE: /tmp/datum-credentials.json +``` + +## Kubernetes + +Create a Kubernetes secret from the credentials file: + +```text +kubectl create secret generic datum-credentials \ + --from-file=credentials.json=/path/to/credentials.json +``` + +Mount it into your pod and point the environment variable at it: + +```yaml +env: + - name: DATUM_CREDENTIALS_FILE + value: /var/secrets/datum/credentials.json +volumeMounts: + - name: datum-credentials + mountPath: /var/secrets/datum + readOnly: true +volumes: + - name: datum-credentials + secret: + secretName: datum-credentials +``` + +## Environment variable + +Any tool or SDK that respects `DATUM_CREDENTIALS_FILE` will authenticate automatically when the variable is set: + +```text +export DATUM_CREDENTIALS_FILE=/path/to/credentials.json +``` + +This works in any language or runtime — no SDK integration required. diff --git a/platform/machine-accounts.mdx b/platform/machine-accounts.mdx new file mode 100644 index 0000000..fb30e97 --- /dev/null +++ b/platform/machine-accounts.mdx @@ -0,0 +1,48 @@ +--- +title: "Machine Accounts" +description: "Create non-human identities for applications, CI/CD pipelines, and services to authenticate with Datum APIs" +--- + +Machine accounts give non-human workloads — CI/CD pipelines, backend services, and scripts — a stable cryptographic identity to call Datum APIs. They authenticate using RSA key pairs rather than shared passwords or long-lived user tokens. + +## When to use machine accounts + +| Use case | Example | +|----------|---------| +| CI/CD pipelines | GitHub Actions deploying resources on every merge | +| Kubernetes workloads | A pod calling the Datum API using a projected secret | +| Backend services | A service authenticating as itself, not as a user | +| Local automation | Scripts that run without a browser-based login | + +## Create a machine account + +1. Open your project in the [Datum Cloud portal](https://cloud.datum.net). +2. Navigate to **Machine Accounts** in the left sidebar. +3. Click **Create machine account**. +4. Enter a lowercase name (e.g. `ci-deploy`) and an optional display name. +5. Choose a key type: + - **Datum-managed** — Datum generates an RSA key pair. The private key is shown **once** at creation time. Download it as a JSON credentials file before closing the wizard. + - **User-managed** — You provide your own RSA public key in PEM format. Datum stores only the public key and never sees your private key. +6. Click **Create**. Once the account's identity email is provisioned, your credentials are ready. + + + For datum-managed keys, the private key is only displayed once. Download the credentials file before closing the wizard — it cannot be recovered later. + + +## Manage keys + +Open a machine account and navigate to the **Keys** tab to add or revoke keys. + +- **Add a key** — create an additional datum-managed or user-managed key at any time. +- **Revoke a key** — immediately invalidates the key. Any tokens issued with it will stop working at expiry. + +To rotate keys with zero downtime: add the new key, update your workloads to use it, then revoke the old key. + +## Assign roles + +Machine accounts are IAM principals like any other member. Assign roles from the **Policy Bindings** tab on the account's detail page, or from **Settings → Members** in your project or organization. + +## Disable or delete an account + +- **Disable** — suspends authentication without removing the account or its keys. Re-enable at any time from the **Overview** tab. +- **Delete** — permanently removes the account and revokes all associated keys. This cannot be undone. From 42e796640e095284ab431570659f97432f81a175 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 15 Apr 2026 09:58:56 -0700 Subject: [PATCH 2/2] docs: consolidate machine accounts into a single page --- docs.json | 1 - platform/machine-account-credentials.mdx | 88 ------------------------ platform/machine-accounts.mdx | 82 ++++++++++++++++++++++ 3 files changed, 82 insertions(+), 89 deletions(-) delete mode 100644 platform/machine-account-credentials.mdx diff --git a/docs.json b/docs.json index 6db527d..3c95431 100644 --- a/docs.json +++ b/docs.json @@ -77,7 +77,6 @@ "platform/activity-logs", "platform/secrets", "platform/machine-accounts", - "platform/machine-account-credentials", "platform/locations" ] }, diff --git a/platform/machine-account-credentials.mdx b/platform/machine-account-credentials.mdx deleted file mode 100644 index 8b95c04..0000000 --- a/platform/machine-account-credentials.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Using Machine Account Credentials" -description: "Authenticate CI/CD pipelines, Kubernetes workloads, and backend services using machine account credentials" ---- - -After [creating a machine account](/platform/machine-accounts), you'll have a credentials file or a key pair to use for authentication. This page covers how to use those credentials in common environments. - -## Credentials file format - -When you create a datum-managed key, Datum returns a JSON credentials file: - -```json -{ - "type": "datum_machine_account", - "client_id": "...", - "private_key_id": "...", - "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...", - "client_email": "my-account@my-namespace.my-project.iam.datum.net" -} -``` - -This file is the only artifact you need to authenticate. Treat it like a password — store it in a secrets manager, never commit it to source control. - -## datumctl - -Point `datumctl` at the credentials file using the `--credentials-file` flag: - -```text -datumctl auth login --credentials-file /path/to/credentials.json -``` - -Or set the environment variable so all subsequent commands pick it up automatically: - -```text -export DATUM_CREDENTIALS_FILE=/path/to/credentials.json -datumctl organizations list -``` - -## GitHub Actions - -Store the contents of the credentials file as a repository or organization secret (e.g. `DATUM_CREDENTIALS`), then write it to disk in your workflow: - -```yaml -- name: Authenticate with Datum - run: echo "$DATUM_CREDENTIALS" > /tmp/datum-credentials.json - env: - DATUM_CREDENTIALS: ${{ secrets.DATUM_CREDENTIALS }} - -- name: Run datumctl - run: datumctl organizations list - env: - DATUM_CREDENTIALS_FILE: /tmp/datum-credentials.json -``` - -## Kubernetes - -Create a Kubernetes secret from the credentials file: - -```text -kubectl create secret generic datum-credentials \ - --from-file=credentials.json=/path/to/credentials.json -``` - -Mount it into your pod and point the environment variable at it: - -```yaml -env: - - name: DATUM_CREDENTIALS_FILE - value: /var/secrets/datum/credentials.json -volumeMounts: - - name: datum-credentials - mountPath: /var/secrets/datum - readOnly: true -volumes: - - name: datum-credentials - secret: - secretName: datum-credentials -``` - -## Environment variable - -Any tool or SDK that respects `DATUM_CREDENTIALS_FILE` will authenticate automatically when the variable is set: - -```text -export DATUM_CREDENTIALS_FILE=/path/to/credentials.json -``` - -This works in any language or runtime — no SDK integration required. diff --git a/platform/machine-accounts.mdx b/platform/machine-accounts.mdx index fb30e97..b292b5a 100644 --- a/platform/machine-accounts.mdx +++ b/platform/machine-accounts.mdx @@ -46,3 +46,85 @@ Machine accounts are IAM principals like any other member. Assign roles from the - **Disable** — suspends authentication without removing the account or its keys. Re-enable at any time from the **Overview** tab. - **Delete** — permanently removes the account and revokes all associated keys. This cannot be undone. + +## Using credentials + +After creating a machine account, you'll have a credentials file to use for authentication. + +### Credentials file format + +When you create a datum-managed key, Datum returns a JSON credentials file: + +```json +{ + "type": "datum_machine_account", + "client_id": "...", + "private_key_id": "...", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...", + "client_email": "my-account@my-namespace.my-project.iam.datum.net" +} +``` + +Treat this file like a password — store it in a secrets manager and never commit it to source control. + +### datumctl + +```text +datumctl auth login --credentials-file /path/to/credentials.json +``` + +Or set the environment variable so all subsequent commands pick it up automatically: + +```text +export DATUM_CREDENTIALS_FILE=/path/to/credentials.json +datumctl organizations list +``` + +### GitHub Actions + +Store the contents of the credentials file as a repository or organization secret (e.g. `DATUM_CREDENTIALS`), then write it to disk in your workflow: + +```yaml +- name: Authenticate with Datum + run: echo "$DATUM_CREDENTIALS" > /tmp/datum-credentials.json + env: + DATUM_CREDENTIALS: ${{ secrets.DATUM_CREDENTIALS }} + +- name: Run datumctl + run: datumctl organizations list + env: + DATUM_CREDENTIALS_FILE: /tmp/datum-credentials.json +``` + +### Kubernetes + +Create a Kubernetes secret from the credentials file: + +```text +kubectl create secret generic datum-credentials \ + --from-file=credentials.json=/path/to/credentials.json +``` + +Mount it into your pod and point the environment variable at it: + +```yaml +env: + - name: DATUM_CREDENTIALS_FILE + value: /var/secrets/datum/credentials.json +volumeMounts: + - name: datum-credentials + mountPath: /var/secrets/datum + readOnly: true +volumes: + - name: datum-credentials + secret: + secretName: datum-credentials +``` + +### Environment variable + +Any tool or SDK that respects `DATUM_CREDENTIALS_FILE` will authenticate automatically when the variable is set: + +```text +export DATUM_CREDENTIALS_FILE=/path/to/credentials.json +```