KilevelDocs
Platform

OAuth2 client credentials

Exchange a client_id and client_secret for a short-lived bearer token that calls the public API and the MCP server with exactly the permissions you granted.

An OAuth2 client is the credential to give an agent, an MCP client, or anything long-running. You hand it a client_id and client_secret; it exchanges them for a token that expires, carries only the permissions you ticked, and can be revoked without touching anything else you have deployed.

Create a client

Open the API page (System → API in the dashboard sidebar). Under Webhook OAuth2 Clients, choose Create Client and set its Kilevel API access — the same permission list an API key uses.

No permissions means no API access

A client with nothing ticked can still authenticate tool-task webhook callbacks, but its tokens are refused by the public API and the MCP server. That is the default, and it is deliberate: widening a credential should be something you did on purpose.

Both halves are shown once, at creation. The client_id is prefixed klv_client_.

Get a token

curl -s -X POST https://api.kilevel.com/api/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$KILEVEL_CLIENT_ID \
  -d client_secret=$KILEVEL_CLIENT_SECRET

HTTP Basic works as well, if your client library prefers it. The response is the standard triple:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens for a client with API access are capped at 24 hours, whatever the client's configured lifetime. Cache the token until it expires rather than minting one per request.

Call the API

curl -s https://api.kilevel.com/api/external/v1/balance \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The same token works on the MCP server. Because every MCP tool call is executed against this API with your credential, a client's permissions decide which tools actually work — a token without Trigger outbound calls can list flows and read history, and fails on placing a call.

Revoking

Revoke the client on the API page, under Webhook OAuth2 Clients. Permissions and revocation are both re-read on every request, so narrowing what a client may do — or revoking it outright — takes effect on its next call rather than whenever its current token would have expired.

Discovery

The API publishes standard metadata, so an OAuth-aware client can configure itself:

https://api.kilevel.com/.well-known/oauth-protected-resource
https://api.kilevel.com/.well-known/oauth-authorization-server

There is no dynamic client registration — the authorization server metadata carries no registration_endpoint, because a client is created by a person who decides what it may do. An agent cannot enrol itself; see auth.md for the machine-readable version of that statement.

Next