---
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
  - `supportsDeliveryAcknowledgement` boolean — Whether the client acknowledges secure credential storage with DELETE

## 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-08-26** `38234fc871e7` — 1 info
  - added the new optional request property `supportsDeliveryAcknowledgement`
- **2026-05-07** `90de04b87133` — 1 warning
  - removed the optional property `error` from the response with the `500` status
- **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/8108f2a53d2e/schema)