---
title: "Create an App Client"
method: POST
path: "/v2/app_clients"
tags: ["Application Clients"]
---

# Create an App Client

`POST /v2/app_clients`

Creates an App Client. An App Client is used for OAuth 2.0 authentication when calling Vectara APIs.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateAppClientRequest — Request to create an App Client that calls Vectara APIs with OAuth 2.0 client credentials.
  - `name` string, required — Name of the client credentials.
  - `description` string — Description of the client credentials.
  - `type` string, required — Always the value `client_credentials`.
  - `api_roles` ApiRole[] — The API roles assigned to the client credentials.
  - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for this App Client.
    - `corpus_key` string, required — The key of the corpus this role applies to.
    - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus.
  - `agent_roles` AgentRole[] — Agent-specific role assignments for this App Client.
    - `agent_key` string, required — The key of the agent this role applies to. For the `agent_end_user` role this is an agent alias key, which shares the same shape.
    - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies.

## Response `201`

An App Client object, used to query the Vectara API with the assigned roles.

- AppClient — An OAuth application client configuration used for authentication.
  - `id` string, required — The Vectara App Client ID. This ID is not used during an OAuth flow. Use this ID within the Vectara API.
  - `name` string, required — The human-readable name of the App Client.
  - `description` string — Description of the App Client.
  - `client_id` string, required — The client ID used with the OAuth flow.
  - `client_secret` string, required — The client secret used in API requests. Keep the secret secure.
  - `api_roles` ApiRole[] — The API roles attached to the App Client.
  - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for this App Client.
    - `corpus_key` string, required — The key of the corpus this role applies to.
    - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus.
  - `agent_roles` AgentRole[] — Agent-specific role assignments for this App Client.
    - `agent_key` string, required — The key of the agent this role applies to. For the `agent_end_user` role this is an agent alias key, which shares the same shape.
    - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies.
  - `api_policy` ApiPolicy — The actions a principal can take on the Vectara platform.
    - `name` string, required — The name of the API role.
    - `allowed_operations` object, required — The operations the API role allows. Each operation may allow only certain resources, described by a map of resource path to resource values. If the value is null, the operation allows any resource.

## Other responses

- `400` — App Client creation request was malformed.
- `403` — Permissions do not allow creating the App Client.

## Changes

- **2026-09-14** `c94fd099d78b` — 1 warning, 1 info
  - added the new `metrics_viewer` enum value to the `api_roles/items/` response property for the response status `201`
  - added the new `metrics_viewer` enum value to the request property `oneOf[#/components/schemas/CreateClientCredentialsRequest]/api_roles/items/`
- **2026-08-05** `fca567a46b3a` — 1 warning, 1 info
  - added the new `agent_end_user` enum value to the `agent_roles/items/role` response property for the response status `201`
  - added the new `agent_end_user` enum value to the request property `oneOf[#/components/schemas/CreateClientCredentialsRequest]/agent_roles/items/role`

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/app_clients/post.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/de6b34bc4a4f?raw)