|
| 1 | +--- |
| 2 | +title: 'Service Accounts' |
| 3 | +description: 'Create and manage machine credentials for automation, CI pipelines, and integrations' |
| 4 | +icon: 'bot' |
| 5 | +--- |
| 6 | + |
| 7 | +Service accounts are **non-human credentials** for automation — CI pipelines, scheduled jobs, and integrations that need to call NVIDIA CCluster APIs without a browser login. Each service account has a **Client ID** and **Client Secret** you use to authenticate programmatically. |
| 8 | + |
| 9 | +Service accounts are **scoped to the user who creates them and the organization they belong to**. You only see and manage service accounts you created in your current organization. API calls made with a service account run as that user within that organization — they cannot access resources in other organizations or service accounts created by other users. |
| 10 | + |
| 11 | +<Note> |
| 12 | +Service accounts authenticate to **NVIDIA CCluster platform APIs** (for example, listing deployments or creating workloads through the SDK). They are separate from [Vault bearer tokens](/resources/vault), which protect your deployed inference endpoints. See [Securing Endpoints](/resources/private) for endpoint access. |
| 13 | +</Note> |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +Before creating a service account, you need: |
| 18 | + |
| 19 | +- An active NVIDIA CCluster account provisioned for your organization |
| 20 | +- Access to the organization where the automation will run — service accounts are tied to **your user** and **that organization** |
| 21 | +- Permissions for the scopes you want to grant — you can only assign scopes you already hold |
| 22 | + |
| 23 | +## Create a service account |
| 24 | + |
| 25 | +1. Log in to the NVIDIA CCluster UI. |
| 26 | +2. Select **Service Accounts** from the sidebar. |
| 27 | +3. Click **Create service account**. |
| 28 | +4. Enter a **Name** (required) and optional **Description** — for example, `CI pipeline` or `nightly-evaluation`. |
| 29 | +5. Select the **Scopes** your automation needs. Only scopes you hold are available; UI-only permissions are not grantable. |
| 30 | +6. Click **Create**. |
| 31 | + |
| 32 | +After creation, a modal displays your **Client Secret**. Copy and store it immediately — **this is the only time the full secret is shown**. |
| 33 | + |
| 34 | +The service account list also shows the **Client ID** for each account. You can copy it at any time from the list. |
| 35 | + |
| 36 | +## Use service account credentials |
| 37 | + |
| 38 | +Store the **Client ID** and **Client Secret** in a secret manager or your CI/CD secret store. Never commit them to source control. |
| 39 | + |
| 40 | +For unattended automation with the `centml` SDK or CLI, set the following environment variables: |
| 41 | + |
| 42 | +```bash |
| 43 | +export CENTML_SERVICE_ACCOUNT_ID="<your_client_id>" |
| 44 | +export CENTML_SERVICE_ACCOUNT_SECRET="<your_client_secret>" |
| 45 | +``` |
| 46 | + |
| 47 | +The SDK uses these credentials to obtain an access token automatically — no browser login required. Once configured, use the client as you would after an interactive `centml login`: |
| 48 | + |
| 49 | +```bash |
| 50 | +ccluster ls |
| 51 | +``` |
| 52 | + |
| 53 | +```python |
| 54 | +import centml |
| 55 | +from centml.sdk.api import get_centml_client |
| 56 | +from centml.sdk import DeploymentType |
| 57 | + |
| 58 | +with get_centml_client() as cclient: |
| 59 | + deployments = cclient.get(DeploymentType.INFERENCE_V2) |
| 60 | + print(deployments) |
| 61 | +``` |
| 62 | + |
| 63 | +<Tip> |
| 64 | +Use one service account per automation or integration so you can rotate or revoke credentials independently. |
| 65 | +</Tip> |
| 66 | + |
| 67 | +## Manage service accounts |
| 68 | + |
| 69 | +From the **Service Accounts** page, you can: |
| 70 | + |
| 71 | +| Action | Description | |
| 72 | +|--------|-------------| |
| 73 | +| **Edit** | Update the name, description, or scopes | |
| 74 | +| **Regenerate secret** | Generate a new Client Secret (shown once) — use this to rotate credentials | |
| 75 | +| **Delete** | Permanently remove the service account | |
| 76 | + |
| 77 | +<Note> |
| 78 | +Deleting a service account takes effect immediately. Any integration using its credentials will stop working. |
| 79 | +</Note> |
| 80 | + |
| 81 | +When you regenerate a secret, copy the new value right away. The previous secret may continue to work until you rotate integrations to the new one. |
| 82 | + |
| 83 | +## Security best practices |
| 84 | + |
| 85 | +- **Least privilege** — grant only the scopes your automation needs. |
| 86 | +- **One account per use case** — separate CI, staging, and production automations. |
| 87 | +- **Rotate regularly** — regenerate secrets on a schedule or after team changes. |
| 88 | +- **Store secrets securely** — use a secret manager or CI secret store, not environment files in your repository. |
| 89 | +- **Revoke promptly** — delete service accounts when an integration is retired. |
| 90 | + |
| 91 | +API requests made with a service account are attributed to the user who created it and that user's organization. |
| 92 | + |
| 93 | +## Limits and important notes |
| 94 | + |
| 95 | +- You can create at most **5 active service accounts** per user per organization. |
| 96 | +- Service accounts belong to the **creating user** and **current organization** — switch organizations in the UI to manage accounts for a different org, or have each team member create their own accounts. |
| 97 | +- The **Client Secret** is shown only once at creation or regeneration — if you lose it, generate a new secret. |
| 98 | +- You cannot grant scopes you do not hold. |
| 99 | +- Scopes are fixed at creation time based on your permissions when you create or update the account; if your role changes later, review and update service account scopes as needed. |
| 100 | + |
| 101 | +## What's next |
| 102 | + |
| 103 | +<CardGroup cols={3}> |
| 104 | + <Card |
| 105 | + title="Client Setup" |
| 106 | + icon="terminal" |
| 107 | + href="/clients/setup" |
| 108 | + > |
| 109 | + Install and configure the NVIDIA CCluster client. |
| 110 | + </Card> |
| 111 | + <Card |
| 112 | + title="Python SDK Reference" |
| 113 | + icon="python" |
| 114 | + href="/clients/sdk" |
| 115 | + > |
| 116 | + Access NVIDIA CCluster programmatically using Python. |
| 117 | + </Card> |
| 118 | + <Card |
| 119 | + title="Managing Vault Objects" |
| 120 | + icon="key-skeleton-left-right" |
| 121 | + href="/resources/vault" |
| 122 | + > |
| 123 | + Generate bearer tokens and other secrets for deployments and endpoints. |
| 124 | + </Card> |
| 125 | +</CardGroup> |
0 commit comments