> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agent home for Datum, with what it is, pricing, and how to act: https://agents.datum.net
> If you can only fetch URLs: read https://www.datum.net/docs/llms.txt in full and open the most specific page for the task. Commands, limits, and field paths are on task, operations, and limits pages, not on section overviews. Pages described as "Documentation is coming soon" are placeholders.
> If you have a shell or can save files: download https://www.datum.net/docs/llms-full.txt (every page, about 740 KB) once and search it with grep, instead of fetching pages one at a time.
> datumctl describes itself: `datumctl api-resources` lists resource types and `datumctl explain <resource>` shows a schema. To act on live resources, use Datum MCP or datumctl. To search the docs, use the Docs MCP server at https://www.datum.net/docs/mcp.

# Service Accounts

> Create non-human identities for applications, CI/CD pipelines, and services to authenticate with Datum APIs

Service 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 service 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 service account

The Cloud Portal offers two starting points. **CI/CD Pipeline** generates a credentials file to store as a secret in GitHub Actions, GitLab CI, or another pipeline, with setup instructions. **Service** gives a backend service or workload a stable identity to call Datum APIs, with credentials you mount as a Kubernetes Secret or environment variables.

![The Add a Service Account tab, with two cards: CI/CD Pipeline and Service, each with a Create a service account button](https://mintcdn.com/datum-4926dda5/Xc9AnQUL-oEENeSS/images/service-account-types.png?fit=max\&auto=format\&n=Xc9AnQUL-oEENeSS\&q=85\&s=c568a2dfab7b172a12e150a0d03073a7)

Choose the kind of service account to create

1. Open your project in the [Datum Cloud portal](https://cloud.datum.net).
2. Navigate to **Service Accounts** in the left sidebar.
3. Select **Create service account**.
4. Enter a lowercase name (e.g. `ci-deploy`) and an optional display name.

   ![Service account creation form](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=63d5a70deedcf2035fb889253c4766cb)
5. Select 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.

     ![Key type selection](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-1.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=1c7557d696c6b4e37dcd9c0beb6e5236)
6. Select **Create**. Once the account's identity email is provisioned, your credentials are ready.

   ![Service account created, credentials available to download](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-2.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=db81205c074e3d3eb57a8a73c109f65b)

> [!NOTE]
>
> 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 service 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

Service accounts are IAM principals like any other member. Assign roles from the **Roles** tab on the account's detail page, or from **Settings → Members** in your project or organization.

![Policy Bindings form showing role assignments](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-3.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=fd208ebf6322e8c8a4c68c75f9d7e4c0)

## 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.

## Using credentials

After creating a service 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. For its fields, see [The credentials file](/docs/datumctl/auth/service-accounts.md#the-credentials-file).

**Treat this file like a password** — store it in a secrets manager and never commit it to source control.

### datumctl

Log in with the credentials file, then run commands as the service account:

```bash theme={null}
datumctl login --credentials /path/to/credentials.json
datumctl get organizations
```

Service-account login doesn't prompt you to pick a context, so pass `--organization` or `--project` on each command, or set a context. For custom environments and more, see [Service accounts in datumctl](/docs/datumctl/auth/service-accounts.md#log-in-with-a-credentials-file). For a pipeline, see [Automating datumctl in CI/CD](/docs/datumctl/cicd/automating.md).

### GitHub Actions

Store the contents of the credentials file as a repository or organization secret, such as `DATUM_SA_CREDENTIALS`, and pass it to the `datumctl` setup action. The action logs in as the service account, so later steps run `datumctl` without a login command. For the full workflow, see [GitHub Actions](/docs/datumctl/cicd/github-actions.md).

### Kubernetes

Create a Kubernetes secret from the credentials file:

```text theme={null}
kubectl create secret generic datum-credentials \
  --from-file=credentials.json=/path/to/credentials.json
```

Mount it into your pod, then log in with the mounted file before running `datumctl`:

```yaml theme={null}
volumeMounts:
  - name: datum-credentials
    mountPath: /var/secrets/datum
    readOnly: true
volumes:
  - name: datum-credentials
    secret:
      secretName: datum-credentials
```

```bash theme={null}
datumctl login --credentials /var/secrets/datum/credentials.json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.