---
title: "Create a new CLI session with auth code"
method: POST
path: "/api/v3/cli/create-session"
tags: ["CLI Authentication", "x-internal"]
---

# Create a new CLI session with auth code

`POST /api/v3/cli/create-session`

Generates a new CLI session with a random 6-character code. This endpoint is the first step in the CLI authentication flow, creating a session that can later be linked to a user account. The generated code is displayed to the user in the CLI and should be entered in the web interface to complete authentication. Optionally accepts a scope ('project' or 'user') and a source string.

## Request body

- object
  - `scope` 'project' | 'user' — Key scope. 'project' (default) returns a project-level API key; 'user' returns a user-level API key valid across projects.
  - `source` string — Free-form string describing the source, e.g. 'Johns MacBook (darwin, v1.2.3)'

## Response `201`

CLI session created successfully with a unique ID and temporary authentication code

- object
  - `id` string, required — Unique identifier for the CLI session. UUID v4 format used for tracking and retrieval.
  - `code` string, required — The 6-character hexadecimal code used for CLI login
  - `expiresAt` string, required — The ISO timestamp when the session expires
  - `status` 'pending' | 'linked', required — The current status of the session
  - `scope` 'project' | 'user', required — The key scope for this session

## Other responses

- `400` — Bad request - Invalid parameters or malformed request
- `500` — Internal server error - Failed to create CLI session due to server-side issue

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api/versions/df7478fc8f3b/schema)