> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/settings-and-administration/service-accounts.md).

# Service Accounts

{% hint style="success" %}
**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.
{% endhint %}

## Overview

A service account is a non-human employee <code class="expression">space.vars.entity</code> 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 <code class="expression">space.vars.timeline</code>, 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](https://support.kizen.com/support/solutions/articles/154000255193-service-accounts-overview) support article.

### Account Types

Two account types exist:

| Type                  | Description                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 <code class="expression">space.vars.automation</code> Code Step. The platform provides a preconfigured client, `kizen.api`, that authenticates automatically as the business's <code class="expression">space.vars.automation</code> Code Account.

* **No integration secrets needed.** Do not create a separate integration service account just to call Kizen from a code step.
* **Use** `kizen.api` **directly.** It is preconfigured with the <code class="expression">space.vars.automation</code> 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 <code class="expression">space.vars.objects</code> that behave like standard `requests` responses, with `.json()` and `.raise_for_status()` available.

Here's an example request:

```python
res = kizen.api.get("/custom-objects")
res.raise_for_status()
number_of_custom_objects = res.json()['count']
```

***

## 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:

| Level           | Allowed Actions                                      |
| --------------- | ---------------------------------------------------- |
| **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 <code class="expression">space.vars.automation</code> Code Account cannot be deleted, renamed, or have its `api_name` changed.
* 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=true` to include them.

***

## What's Next

The most common next step after reading this reference is writing or modifying an <code class="expression">space.vars.automation</code> code step that uses `kizen.api`. See [Agentic Workflow Code Steps ](/docs/concepts/agentic-workflows/automation-code-steps.md)for the full authoring guide, including available helpers, runtime behavior, and patterns for working with Kizen data from inside a step.

<details>

<summary>Related Topics</summary>

* [Authentication](/docs/developers/authentication.md)
* [Agentic Workflow Code Steps](/docs/concepts/agentic-workflows/automation-code-steps.md)
* [Agentic Workflows](/docs/concepts/agentic-workflows.md)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.kizen.com/docs/settings-and-administration/service-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.