---
title: "Create an API auth session"
method: POST
path: "/v1/api/auth/sessions"
tags: ["auth"]
---

# Create an API auth session

`POST /v1/api/auth/sessions`

Creates a new browser-based auth session for CLI or other API clients. The returned verification URL should be opened in the user's browser to complete authentication.

## Request body

- object
  - `deviceName` string — Name of the device requesting access (e.g. user@MacBook-Pro.local)
  - `callbackUrl` string, uri — HTTPS callback URL to redirect the user to after approving the session

## Response `201`

Session created successfully

- object
  - `sessionId` string, required — Unique session identifier
  - `verificationUrl` string, required — URL to open in the browser to approve the session
  - `expiresAt` string, required — ISO 8601 timestamp when the session expires

## Other responses

- `500` — Internal server error

## Changes

- **2026-03-30** `4a10ba483067` — 1 info
  - added the new optional request property `callbackUrl`
- **2026-03-24** `66520a246641` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/changes/v1/api/auth/sessions/post.md)

---

[API](https://skmtc.dev/paragraph-xyz/apis/paragraph-api.md) · [All operations](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/paragraph-xyz/paragraph-api/revisions/a70bb5fa8a85/schema)