Service Accounts
Audience: Developers, Technical Builders
Purpose: Provides a complete technical reference for service accounts: how to use the new kizen.api client in Code Steps, how authentication works under the hood (signed keys vs. stored keys), the full REST API surface for managing integration accounts programmatically, and the extension points for engineers adding new account types or endpoints.
Overview
A service account is a non-human employee Record distinguished by its account_type field. Any value starting with service_ is treated as a service account. Service accounts carry permission groups, can authenticate via API, and appear in the Timeline, but are excluded from billing counts, the public employee list, and (by default) team typeahead.
For a non-technical introduction to service accounts, see the Service Accounts support article.
Account Types
Two account types exist:
service_automation
The Agentic Workflow Code Account, auto-provisioned per business. Used by Code Steps. Cannot be deleted, renamed, or have its api_name changed.
service_integration
Integration accounts, created manually or via API for external integrations such as Zapier or custom scripts.
A service account's status is either Active or Suspended. Status cannot be changed manually; service account is suspended automatically when its associated integration is disabled.
Email is auto-generated and never used for login. The default domain is serviceaccounts.kizen.com
Kizen API Access from Code Steps
You do not need to create or manage an integration service account to call Kizen APIs from an Agentic Workflow Code Step. The platform provides a preconfigured client, kizen.api, that authenticates automatically as the business's Agentic Workflow Code Account.
No integration secrets needed. Do not create a separate integration service account just to call Kizen from a code step.
Use
kizen.apidirectly. It is preconfigured with the Agentic Workflow service account; you do not create it, configure it, or pass credentials.The API root URL is built in. Pass only the path, not the full URL.
Correct:
res = kizen.api.get("/custom-objects")Incorrect:
res = kizen.api.get("https://app.fmo.kizen.com/api/custom-objects")
The client supports the standard HTTP verbs — get, post, patch, put, delete — and returns response Objects that behave like standard requests responses, with .json() and .raise_for_status() available.
Here's an example request:
Authentication
Authentication is handled automatically for each account type:
Agentic Workflow Code Account: Uses short-lived signed keys minted per execution when calling the platform via
kizen.api. No credential management is required.Integration Service Accounts: Use stored API keys. Each account supports up to two keys (primary and secondary). Rotating a key promotes the new key to primary and demotes the previous primary to secondary.
Permissions and Guardrails
Management is governed by the MANAGE_SERVICE_ACCOUNTS settings permission. Three permission levels apply:
View (Read)
List, retrieve, view primary/secondary tokens
Write
Create, update, rotate token, delete secondary token
Remove
Archive (delete) an integration account
Additional guardrails:
A service account cannot create its own API keys.
A service account can export business config but cannot import it.
The Agentic Workflow Code Account cannot be deleted, renamed, or have its
api_namechanged.Service accounts are excluded from billing seat counts and the public employee list.
Service accounts are excluded from team typeahead by default. Pass
include_service_accounts=trueto include them.
What's Next
The most common next step after reading this reference is writing or modifying an Agentic Workflow code step that uses kizen.api. See Agentic Workflow Code Steps for the full authoring guide, including available helpers, runtime behavior, and patterns for working with Kizen data from inside a step.
Last updated
Was this helpful?