> ## Documentation Index > Fetch the complete documentation index at: https://team.k0labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Update service account > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Update mutable fields on a service account. Supports changing the display name, description, roles, and status. Only tenant administrators can update service accounts. Non-admin callers receive 404 to prevent resource enumeration. Role changes follow the scope-down principle: the calling administrator can only assign roles they themselves hold within the service account's scope. ## OpenAPI ````yaml api-docs/k0rdent-api.json patch /v1/regions/global/iam/service-accounts/{id} openapi: 3.1.0 info: title: K0rdent AI API version: 0.2.0-draft description: > OpenAPI specification for the K0rdent AI GPU-as-a-Service platform. **Custom Extensions:** - `x-visibility`: Endpoint visibility — `internal` (Atlas only), `public` (Arc only), `[internal, public]` (common) - `x-status`: Implementation status — `mvp`, `tbd`, `blocked`, `stretch` - `x-source`: Source document reference or `TBD` for fields pending confirmation **Error Model:** Standard `{ error: { code, message, details[] } }` envelope. **Pagination:** All list endpoints support two modes: - **Cursor** (`pageToken` + `pageSize`): Use for frequently updated resources. Prevents skipped or duplicated items across pages. `nextPageToken` is returned; `total` is not. - **Offset** (`offset` + `pageSize`): Use for stable resources. Returns `total` for page-count UIs. `nextPageToken` is not returned. `pageToken` and `offset` are mutually exclusive. Default `pageSize` is 50, maximum is 500. servers: - url: https://api.k0rdent.ai description: K0rdent AI API Gateway security: - bearerAuth: [] tags: - name: clusters description: Kubernetes cluster management - name: kubeconfigs description: Kubeconfig issuance and management - name: instances description: VM and baremetal instance lifecycle - name: networks description: Network configuration and topology - name: addresses description: IP address management - name: servers description: Bare metal server lifecycle management - name: organizations description: Organization (tenant) management - name: projects description: Project resource grouping - name: authentication description: Authentication and session management - name: users description: User management - name: groups description: User group management - name: roles description: RBAC role definitions - name: policies description: IAM policy bindings - name: providers description: Identity provider configuration - name: token description: > Generate access token via multiple grant types (authorization_code, api_key, client_credentials). - name: check description: > Evaluate permissions for a principal against actions and resources. Supports single and bulk checks (up to 100). - name: introspect description: > Token introspection per RFC 7662. Validate token activity and retrieve full decoded claims. - name: revoke description: > Token revocation per RFC 7009. Explicitly invalidate access tokens before natural expiration. - name: sessions description: > Manage user browser sessions. Supports listing active sessions, creating a new session (login), and ending the current session (logout). - name: apikeys description: > Manage API keys for programmatic access. API keys are bound to a user and inherit a dynamic subset of the user's privileges, evaluated at token-mint time. Keys are scoped to a level in the resource hierarchy (organization, or project). - name: serviceaccounts description: | Manage service accounts for machine-to-machine and infrastructure access. Service accounts are independent principals with their own identity, role bindings, and credentials. They survive user off-boarding and are managed exclusively by tenant administrators. paths: /v1/regions/global/iam/service-accounts/{id}: parameters: - name: id in: path required: true description: Service account resource identifier. schema: type: string patch: tags: - serviceaccounts summary: Update service account description: > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Update mutable fields on a service account. Supports changing the display name, description, roles, and status. Only tenant administrators can update service accounts. Non-admin callers receive 404 to prevent resource enumeration. Role changes follow the scope-down principle: the calling administrator can only assign roles they themselves hold within the service account's scope. operationId: updateServiceAccount requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: displayName: type: string description: Updated display name. minLength: 1 maxLength: 255 description: type: string description: Updated description. maxLength: 1024 roles: type: array items: type: string description: | Updated role bindings. Each must be a valid org-defined role slug held by the calling administrator within the service account's scope. status: type: string enum: - active - disabled description: | Toggle service account status. When disabled, all credentials are effectively unusable. Can be re-enabled by setting back to active. responses: '200': description: Updated service account metadata. content: application/json: schema: $ref: '#/components/schemas/ServiceAccount' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': description: | Validation error. Role slug not recognized or not held by the calling administrator. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ServiceAccount: type: object description: | Service account for machine-to-machine and infrastructure access. Service accounts are independent principals with their own identity and role bindings. They are scoped to a level in the resource hierarchy (organization, or project) and survive the off-boarding of the user who created them. Authentication uses client_id (on this resource) combined with a client_secret (from a credential sub-resource) via the grant_type=client_credentials flow. Only tenant administrators can create and manage service accounts. required: - id - uid - displayName - clientId - scope - scopeId - status - createdAt - createdBy properties: selfLink: type: string format: uri description: Server-defined URL for this resource. readOnly: true example: /v1/iam/service-accounts/sa-pipeline-prod uid: type: string format: uuid description: Server-generated UUID. Immutable. readOnly: true id: type: string description: | Resource identifier. Provided by the client at creation or server-generated if omitted. Must be 1-63 lowercase characters matching [a-z]([-a-z0-9]*[a-z0-9])?. Immutable after creation. pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ minLength: 1 maxLength: 63 example: sa-pipeline-prod displayName: type: string description: Human-readable display name for the service account. minLength: 1 maxLength: 255 example: Production CI/CD Pipeline description: type: string description: Optional description of the service account's purpose. maxLength: 1024 clientId: type: string description: | Unique client identifier for OAuth2 client_credentials flow. Server-generated, immutable. Used together with a credential's client_secret to authenticate at the token endpoint. readOnly: true example: sa-pipeline-prod@myorg.iam scope: type: string enum: - organization - project description: | The level in the resource hierarchy this service account operates within: - organization: access across all projects (subject to assigned roles). - project: restricted to a single project. Subject to org-level policy constraints. example: project scopeId: type: string description: | Resource identifier corresponding to the scope level: - organization scope: the organization ID. - project scope: a project ID. example: proj-abc123 roles: type: array items: type: string description: | Role bindings assigned directly to this service account. Unlike API keys, service account roles are not inherited from a user — they are explicitly granted. Each role must be a valid org-defined role slug. The assigning administrator can only grant roles they themselves hold within the service account's scope (scope-down principle). Effective privileges are bounded by the scope. example: - compute.deployer - storage.writer status: type: string enum: - active - disabled description: | Current service account status. - active: credentials can be used to mint tokens. - disabled: all credentials are temporarily unusable. Can be re-enabled via PATCH. readOnly: true example: active createdBy: type: string description: | User ID of the tenant administrator who created this service account. readOnly: true example: user-admin-001 createdAt: type: string format: date-time description: Timestamp when the service account was created. readOnly: true updatedAt: type: string format: date-time description: Timestamp of the last metadata change. readOnly: true activeCredentialCount: type: integer description: | Number of active (non-expired) credentials on this service account. Maximum of 5 credentials allowed. readOnly: true example: 2 Error: type: object description: Standard error response properties: error: type: object properties: code: type: integer description: HTTP status code message: type: string description: Error message details: type: array items: type: object description: Additional error details responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: | The request conflicts with the current state of a resource. Common causes include attempting to create a resource with an identifier that already exists, or performing a state transition that is not permitted (e.g., re-enabling an expired API key, rotating a disabled key). content: application/json: schema: $ref: '#/components/schemas/Error' examples: duplicateId: summary: Resource ID already exists value: code: CONFLICT message: A resource with id 'my-deploy-key' already exists. invalidStateTransition: summary: Invalid state transition value: code: CONFLICT message: Cannot rotate a disabled API key. Re-enable it first. InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication using OAuth2/OIDC tokens ````