Create a service account

POST

/v1/service-accounts

const url = 'https://example.com/v1/service-accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","description":"example","grants":[{"kind":"tenant-admin"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/service-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "grants": [ { "kind": "tenant-admin" } ] }'

A named, non-human principal with its first grants, written before it is returned. It isn’t a tenant member unless a grant makes it one ({kind: 'tenant-member'}: read the tenant’s settings); give it only what its job needs. Mint its keys at POST /v1/tokens with for. Tenant admins only. Mounted when the deployment supplies a ServiceAccountBinding.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

object

name

required

Lowercase letters, digits and hyphens, e.g. acme-ci.

string

/^[a-z0-9][a-z0-9-]{0,62}$/

description

string

<= 500 characters

grants

Written before the account is returned, so its first key works at once.

Array

One of: discriminator: kind

Tenant admin.

object

kind

required

string

Allowed values: tenant-admin

A role to give on one project; it replaces the account’s role there.

object

kind

required

string

Allowed values: project

projectId

required

string format: uuid

role

required

A role to give on a project: owner, admin, editor or viewer, each including the ones after it. member is refused (400): give viewer.

string

Allowed values: viewer editor owner admin

Responses

201

Created.

application/json

A named, non-human principal (service_account:<id>) for an app, a pipeline or a schedule. It acts through API keys minted for it.

object

serviceAccountId

required

string

name

required

Unique among the tenant’s active accounts.

string

description

string

grants

required

Array

One of: discriminator: kind

Tenant admin.

object

kind

required

string

Allowed values: tenant-admin

A role on one project; it replaces the account’s role there.

object

kind

required

string

Allowed values: project

projectId

required

string format: uuid

role

required

Role on a project, as read. member is only read, on a role given before it was retired: it grants what viewer does, and writes refuse it.

string

Allowed values: viewer editor owner admin member

createdBy

Who created it: user:<id> or service_account:<id>.

string

createdAt

required

string format: date-time

unregisteredAt

Set once unregistered: it has no grants, and its keys no longer work.

string format: date-time

projectId

Set on a project’s own account: made by the first trigger that runs as the project (runAsProject), with the editor role on it. It runs only the triggers with runAsProject, not the project’s other shared triggers. It has no keys, and its grant is fixed. Unregistering it stops those triggers until an admin takes each over; deleting the project unregisters it.

string

Example

{
  "grants": [
    {
      "kind": "tenant-admin"
    }
  ]
}

400

Malformed request body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Not a tenant admin.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

A grant names no project of this tenant (project-not-found).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

An active service account has the name (service-account-name-taken), or an idempotency conflict.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Create a service account

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated