Authentication
Audience: Developers
Purpose: Explains the two supported authentication methods for the Kizen API, token-based authentication and OAuth2, including setup steps, required headers, and security best practices.
Overview
Every request to the Kizen 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.
There are two supported methods:
Token-based authentication
Recommended starting point for most integrations
OAuth2
More secure option for production integrations
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 Kizen API. It uses an API key tied to a specific Kizen 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 Kizen API must include the following three headers:
X-API-KEY: authenticates the request, acting as the password for the user IDX-BUSINESS-ID: scopes the request to the correct Kizen business accountX-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.
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.
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 Kizen. To get started, contact your Kizen support representative with the following information:
Your application name
Environments you need to support
Redirect URI or URIs your integration will use
Kizen will then provide you with a Client ID and Secret via secure communication.
Access and refresh tokens can be revoked at any time via API call or through the My Profile page in Kizen.
What's Next
Now that you understand how authentication works, start with Generating your API Credentials, then move on to Create Your First API Call to test your credentials and confirm everything is working in the test environment.
Last updated
Was this helpful?