---
title: "PUT /gateway/v2/service-account"
method: PUT
path: "/gateway/v2/service-account"
tags: ["cli_gateway-service-account_gateway_v2_10"]
---

# PUT /gateway/v2/service-account

`PUT /gateway/v2/service-account`

## Request

- Base URL: `https://developers.conduktor.io` (the document declares no server; this is the origin it was published from)
- URL: `https://developers.conduktor.io/gateway/v2/service-account`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/conduktor/apis/conduktor-gateway-api/docs/gateway/v2/service-account/put.ts> (a function with typed inputs; its response is checked against the schema)

[![Generally Available](https://img.shields.io/badge/Lifecycle-Generally%20Available-blue)](#tag/Versioning)

Upsert a service account

## Query parameters

- `dryMode` boolean

## Request body

- union
  - External
    - `kind` string, required: The kind of the service account
    - `apiVersion` string, required: The api version of the service account
    - `metadata` ExternalMetadata, required: Metadata of the service account
      - `name` string, ^[a-zA-Z0-9_.,=-]{3,64}$, required: The name of the service account (identifier)
      - `vCluster` string, ^[a-zA-Z0-9._-]+$: The name of the virtual cluster the service account belongs to. If not provided, the service account will be created in the default `passthrough` virtual cluster.
    - `spec` ExternalSpec, required: Spec of the service account
      - `externalNames` string[]: List of the external names of the service account. Used to keep a fixed reference of the service account in interceptors or groups if the values of the external user DB happen to change (ex: OIDC principal, key in delegated auth mode with Confluent etc...) At the moment, an external service account should have exactly one external name (The support for many external names will be available soon)
      - `type` 'EXTERNAL', required: The type of the service account : `LOCAL` or `EXTERNAL` (case insensitive)
  - Local
    - `kind` string, required: The kind of the service account
    - `apiVersion` string, required: The api version of the service account
    - `metadata` LocalMetadata, required: Metadata of the service account
      - `name` string, ^[a-zA-Z0-9_.,=-]{3,64}$, required: The name of the service account (identifier)
      - `vCluster` string, ^[a-zA-Z0-9._-]+$: The name of the virtual cluster the service account belongs to. If not provided, the service account will be created in the default `passthrough` virtual cluster.
    - `spec` LocalSpec, required: Spec of the service account
      - `type` 'LOCAL', required: The type of the service account : `LOCAL` or `EXTERNAL` (case insensitive)

## Response `200`

- ApplyResultGatewayServiceAccount
  - `resource` union, required
    - External
      - `kind` string, required: The kind of the service account
      - `apiVersion` string, required: The api version of the service account
      - `metadata` ExternalMetadata, required: Metadata of the service account
        - `name` string, ^[a-zA-Z0-9_.,=-]{3,64}$, required: The name of the service account (identifier)
        - `vCluster` string, ^[a-zA-Z0-9._-]+$: The name of the virtual cluster the service account belongs to. If not provided, the service account will be created in the default `passthrough` virtual cluster.
      - `spec` ExternalSpec, required: Spec of the service account
        - `externalNames` string[]: List of the external names of the service account. Used to keep a fixed reference of the service account in interceptors or groups if the values of the external user DB happen to change (ex: OIDC principal, key in delegated auth mode with Confluent etc...) At the moment, an external service account should have exactly one external name (The support for many external names will be available soon)
        - `type` 'EXTERNAL', required: The type of the service account : `LOCAL` or `EXTERNAL` (case insensitive)
    - Local
      - `kind` string, required: The kind of the service account
      - `apiVersion` string, required: The api version of the service account
      - `metadata` LocalMetadata, required: Metadata of the service account
        - `name` string, ^[a-zA-Z0-9_.,=-]{3,64}$, required: The name of the service account (identifier)
        - `vCluster` string, ^[a-zA-Z0-9._-]+$: The name of the virtual cluster the service account belongs to. If not provided, the service account will be created in the default `passthrough` virtual cluster.
      - `spec` LocalSpec, required: Spec of the service account
        - `type` 'LOCAL', required: The type of the service account : `LOCAL` or `EXTERNAL` (case insensitive)
  - `upsertResult` 'Created' | 'NotChanged' | 'Updated', required: The result of the upsert operation (created, updated, not changed)

## Other responses

- `400`: The request is not valid
- `401`: The given credentials are not valid
- `403`: The required feature is not included in the current license
- `404`: Virtual cluster ... not found.
- `409`: Service account ... already exists in the given virtual cluster or the principal (...) is already taken.
- `500`: An unexpected error occurred in the server

---

[API](https://skmtc.dev/conduktor/apis/conduktor-gateway-api.md) - [All operations](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/revisions/73ad742aa630?raw)