Grant a service account

POST

/v1/service-accounts/{serviceAccountId}/grant

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

• Same-origin — path relative to the deployment root.

Tenant admin, or a role on a project (replacing the account’s role there). Written before the call answers. Tenant admins only.

Authorizations

• bearerAuth

Parameters

Path Parameters

serviceAccountId

required

string

The service account id.

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

Media typeapplication/json

One of: discriminator: kind

object

Tenant admin.

object

kind

required

string

Allowed values: tenant-admin

object

Tenant member: read the tenant’s settings (providers, policies, adapters, signing keys, deployments), not its projects. A service account has it only when granted; a person has it from being added.

object

kind

required

string

Allowed values: tenant-member

object

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

200

The account, with its grants.

Media typeapplication/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

object

Tenant admin.

object

kind

required

string

Allowed values: tenant-admin

object

Tenant member: read the tenant’s settings (providers, policies, adapters, signing keys, deployments), not its projects. A service account has it only when granted; a person has it from being added.

object

kind

required

string

Allowed values: tenant-member

object

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.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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

No such service account (service-account-not-found), or no such project (project-not-found).

Media typeapplication/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

The account is unregistered (service-account-unregistered), or a project’s own account, whose grant is fixed (service-account-project-owned), or an idempotency conflict.

Media typeapplication/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).

Media typeapplication/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).

Media typeapplication/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"
  }
}

See also

• GET /v1/service-accounts/{serviceAccountId}: Read a service account
• POST /v1/service-accounts/{serviceAccountId}/ungrant: Remove a grant from a service account
• POST /v1/service-accounts/{serviceAccountId}/unregister: Unregister a service account
• Error code project-not-found
• Error code request-too-large
• Error code service-account-not-found
• Error code service-account-project-owned
• Error code service-account-unregistered
• Every error code