# Authentication

{% hint style="success" %}
**Audience:** Developers

**Purpose:** Explains the two supported authentication methods for the <code class="expression">space.vars.Kizen\_company\_name</code> API, token-based authentication and OAuth2, including setup steps, required headers, and security best practices.
{% endhint %}

## **Overview**

Every request to the <code class="expression">space.vars.Kizen\_company\_name</code> API must be authenticated. Authentication tells the API who is making the request, which business account to scope it to, and whether that user has permission to access the requested data.&#x20;

There are two supported methods:&#x20;

* **Token-based authentication**
  * Recommended starting point for most integrations
* **OAuth2**
  * More secure option for production integrations&#x20;

This topic covers both methods and helps you decide which one fits your use case.

***

## **Token-Based Authentication**

Token-based authentication is the simplest and most common way to get started with the <code class="expression">space.vars.Kizen\_company\_name</code> API. It uses an API key tied to a specific <code class="expression">space.vars.Kizen\_company\_name</code> user, along with that user's business ID and user ID. All three are required on every request.

### **Setting Up a Dedicated API User**

Before creating an API key, it’s strongly recommended to set up a dedicated user specifically for API access rather than using a personal account. API keys inherit the permissions of the user they belong to, so using a personal account would grant the integration full access to everything that user can do.

Instead, create a dedicated API user with a tightly scoped permission group that includes only what the integration needs. Then assign that permission group to the API user and generate the API key from that account. This approach limits access, and makes it easier to manage, audit, and revoke permissions without affecting other users.

### **Required Headers**

Once you have an API key, every call to the <code class="expression">space.vars.Kizen\_company\_name</code> API must include the following three headers:

* `X-API-KEY`**:** authenticates the request, acting as the password for the user ID
* `X-BUSINESS-ID`**:** scopes the request to the correct <code class="expression">space.vars.Kizen\_company\_name</code> business account
* `X-USER-ID`**:** identifies the user, determining which records and features are accessible based on their permissions

The business ID and user ID can both be found on the My Profile page when viewing an existing API key. For more information on Generating or Revoking API Keys, see [Generate API Credentials](/docs/developers/building-with-apis/generating-api-credentials.md).

***

## **OAuth2 Authentication**

OAuth2 is the more secure option for production integrations. Unlike token-based authentication, it keeps static credentials out of your integration entirely. It uses an Authorization Code flow with Proof Key for Code Exchange (PKCE), short-lived access tokens, and automatic token rotation, making it better suited for integrations that require delegated access or need to act on behalf of multiple users.

### **How It Works**

Access tokens expire after 1 hour and are refreshed using a refresh token, which expires after 48 hours. Each refresh issues a new refresh token and invalidates the old one, with a 5-minute grace period to handle network failures.&#x20;

Because of this rotation behavior, always use a singleton pattern when refreshing tokens to avoid race conditions.

### **Configuration**

Once your client application has been set up, configure your integration as follows:

* **Authorize URI**: <https://app.go.kizen.com/oauth2/authorize/>
* **Token URI:** <https://app.go.kizen.com/oauth2/token/>
* **Client ID:** provided by Kizen during provisioning
* **Token:** secret provided by Kizen during provisioning
* **Response Type:** Code
* **Response Mode:** form\_post
* **Scope:** read
* **Use PKCE:** True
* **Encryption:** SHA-256

### **Getting Set Up**

OAuth2 client applications are provisioned by <code class="expression">space.vars.Kizen\_company\_name</code>. To get started, contact your <code class="expression">space.vars.Kizen\_company\_name</code> support representative with the following information:&#x20;

* Your application name
* Environments you need to support
* Redirect URI or URIs your integration will use

<code class="expression">space.vars.Kizen\_company\_name</code> will then provide you with a Client ID and Secret via secure communication.&#x20;

Access and refresh tokens can be revoked at any time via API call or through the My Profile page in <code class="expression">space.vars.Kizen\_company\_name</code>.

***

## **What's Next**

Now that you understand how authentication works, start with [Generating your API Credentials](/docs/developers/building-with-apis/generating-api-credentials.md), then move on to [Create Your First API Call](/docs/developers/building-with-apis/creating-your-first-api-call.md) to test your credentials and confirm everything is working in the test environment.


---

# Agent Instructions: 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/developers/authentication.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.