Service Accounts

are the machine principals behind non-human access to Dodil. They are also what API keys bind to under the hood — when you issue an API key without naming a principal, IAM mints a managed service account for it automatically, so for most CI/SDK use cases you never touch this page and can just issue an API key.

Create a Service Account directly when you want to manage the principal yourself, or when your workload needs short-lived JWTs rather than a long-lived key — JWTs verify against public JWKS and so work on every endpoint, including the edge/worker endpoints that reject dk_ API keys (see API key vs service account). You create the account in the console, generate a secret, then give it the minimum permissions (policies) needed to access your resources.

Where to find Service Accounts in the console

1. Open the Dodil Console.
2. In the top-right corner, open the workspace/organization dropdown.
3. Select IAM.
4. In the IAM sidebar, open Service Accounts.

You can also access it directly at:

• Link to ServiceAccounts 

Create a Service Account

1. Click Create Service Account.
2. Give it a clear name, usually based on your app or environment, for example:
   • my-app-dev
   • my-app-prod
   • ci-worker
3. Click Create.

After creation, you will have a ServiceAccountID. This is the identifier your SDK/API uses as the “client id”.

Generate and save the secret

When you create the Service Account, the console generates a secret.

• The secret is typically shown only once.
• Copy it immediately and store it in a safe place (password manager / secret manager).

You will use the ServiceAccountID and secret in your application environment variables.

Example (names may differ depending on your SDK config):

• DODIL_SERVICE_ACCOUNT_ID=<your ServiceAccountID>
• DODIL_SERVICE_ACCOUNT_SECRET=<your secret>

Assign permissions (policies)

A Service Account can only access what it is authorized to access. Permissions are managed through policies (roles).

How policies work

• A policy grants a set of actions (read, write, admin, etc.).
• Policies can apply to:
  • All resources in your organization (default scope), or
  • A specific resource (restricted scope)

Assign policies in the console

1. Go to IAM → Service Accounts.
2. Open your Service Account.
3. Go to Permissions / Policies in the lower section.
4. Add the policies your app needs.

Common examples

If your project needs to read and write K3 storage (buckets, tables, vector), assign:

• k3.editor

If it only reads, prefer:

• k3.viewer

Other common roles: k3.admin (full K3 administration), registry.developer (registry push/pull), git.ci (CI git access). See Roles and Policies for the model.

Restrict a policy to a single resource (DRN)

For stronger security, you can scope a policy to a specific resource using a Dodil Resource Number (DRN).

Example DRN (a K3 bucket):

• drn:dodil:k3:{region}:{org}:bucket/{name}

Where to find the DRN

You can find the DRN in the relevant service dashboard page (for example, a specific bucket’s page). Copy the DRN and attach it to the policy scope when assigning permissions.

Why you should scope permissions

Scoping policies reduces blast radius:

• Your Service Account can only access the resource(s) it truly needs.
• Accidental deletes/writes to other environments (dev vs prod) are less likely.

Recommended setup

• Create separate Service Accounts per environment:
  • my-app-dev
  • my-app-staging
  • my-app-prod
• Give each Service Account the minimum policies needed.
• Scope policies to specific DRNs whenever possible.
• Rotate secrets periodically (and immediately if you suspect exposure).

Next step

Once you have a ServiceAccountID + secret and the right policies assigned, either bind an API key to the account (dodil auth apikey issue --sa <clientId> ...) or exchange the credentials for an access token — see Get an Access Token for the client-credentials flow in curl, Python, Node.js, and Go.