Skip to main content
POST
/
v1
/
regions
/
global
/
iam
/
service-accounts
Create service account
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    displayName: 'Production CI/CD Pipeline',
    scope: 'project',
    scopeId: 'proj-abc123',
    id: '<string>',
    description: '<string>',
    roles: ['compute.deployer', 'storage.writer']
  })
};

fetch('https://api.k0rdent.ai/v1/regions/global/iam/service-accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "sa-pipeline-prod",
  "displayName": "Production CI/CD Pipeline",
  "clientId": "sa-pipeline-prod@myorg.iam",
  "scope": "project",
  "scopeId": "proj-abc123",
  "status": "active",
  "createdBy": "user-admin-001",
  "createdAt": "2023-11-07T05:31:56Z",
  "selfLink": "/v1/iam/service-accounts/sa-pipeline-prod",
  "description": "<string>",
  "roles": [
    "compute.deployer",
    "storage.writer"
  ],
  "updatedAt": "2023-11-07T05:31:56Z",
  "activeCredentialCount": 2
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using OAuth2/OIDC tokens

Body

application/json
​
displayName
string
required

Human-readable display name.

Required string length: 1 - 255
Example:

"Production CI/CD Pipeline"

​
scope
enum<string>
required

The hierarchy level this service account is scoped to. Subject to org-level policy.

Available options:
organization,
project
Example:

"project"

​
scopeId
string
required

Resource identifier for the scope target. Must be a resource the caller has access to.

Example:

"proj-abc123"

​
id
string

Client-provided resource identifier. If omitted, the server generates one. Must match a-z?.

Required string length: 1 - 63
Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
​
description
string

Optional description of purpose.

Maximum string length: 1024
​
roles
string[]

Roles to assign to the service account. Each must be a valid org-defined role slug that the calling administrator holds within the requested scope (scope-down principle).

Example:
["compute.deployer", "storage.writer"]

Response

Service account created. No credentials are included — use POST /iam/service-accounts/{id}/credentials to create a client_secret.

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.

​
uid
string<uuid>
required

Server-generated UUID. Immutable.

​
id
string
required

Resource identifier. Provided by the client at creation or server-generated if omitted. Must be 1-63 lowercase characters matching a-z?. Immutable after creation.

Required string length: 1 - 63
Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
Example:

"sa-pipeline-prod"

​
displayName
string
required

Human-readable display name for the service account.

Required string length: 1 - 255
Example:

"Production CI/CD Pipeline"

​
clientId
string
required

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.

Example:

"sa-pipeline-prod@myorg.iam"

​
scope
enum<string>
required

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.

Available options:
organization,
project
Example:

"project"

​
scopeId
string
required

Resource identifier corresponding to the scope level:

  • organization scope: the organization ID.
  • project scope: a project ID.
Example:

"proj-abc123"

​
status
enum<string>
required

Current service account status.

  • active: credentials can be used to mint tokens.
  • disabled: all credentials are temporarily unusable. Can be re-enabled via PATCH.
Available options:
active,
disabled
Example:

"active"

​
createdBy
string
required

User ID of the tenant administrator who created this service account.

Example:

"user-admin-001"

​
createdAt
string<date-time>
required

Timestamp when the service account was created.

​
selfLink
string<uri>

Server-defined URL for this resource.

Example:

"/v1/iam/service-accounts/sa-pipeline-prod"

​
description
string

Optional description of the service account's purpose.

Maximum string length: 1024
​
roles
string[]

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"]
​
updatedAt
string<date-time>

Timestamp of the last metadata change.

​
activeCredentialCount
integer

Number of active (non-expired) credentials on this service account. Maximum of 5 credentials allowed.

Example:

2