API Reference

Full reference for the Verne Passepartout HTTP API. All endpoints are served from https://api.vernesoft.com.

Examples are shown as raw curl requests and as calls through the official SDKs — see Installation to set one up. SDK snippets assume an initialized verne client with a passepartout key.

1. Authentication

Every request must include a Bearer token in the Authorization header. Passepartout API keys follow the format:

vrn_passepartout_<environment>_<secret>

Prefix	Environment
`vrn_passepartout_test_`	Sandbox — logins run against your test bot.
`vrn_passepartout_live_`	Production — full login pipeline.

Example header:

Authorization: Bearer vrn_passepartout_live_sk_9f8a7...

The key authenticates your application. The access token returned by a completed login (prefixed ppt_live_) represents an authenticated end-user — pass that back to your app's session, not the API key. Keys are scoped to a single tenant and can be rotated from the Dashboard → Keys page.

Bot setup. Before any login works, configure your Telegram bot token (from @BotFather) and enable it on the Dashboard → Passepartout page. Tokens are encrypted at rest with AES-256-GCM.

POST /v1/passepartout/login/start

Begins a Telegram login attempt. Returns a nonce and a deep_link; send the end-user to the deep_link, then poll Get Login Status with the nonce. Takes no request body.

Example Request

curl -X POST https://api.vernesoft.com/v1/passepartout/login/start \
  -H 'Authorization: Bearer vrn_passepartout_test_123'

Response

{
  "nonce": "n_9f2c8a1b",
  "deep_link": "https://t.me/your_bot?start=n_9f2c8a1b",
  "expires_at": "2026-07-25T12:05:00Z"
}

Status Code	Meaning
`200 OK`	Login started; `nonce` and `deep_link` returned.
`401 Unauthorized`	Missing or invalid Bearer token.
`403 Forbidden`	Key lacks the `passepartout` scope.
`409 Conflict`	No bot configured or enabled for this tenant.
`402 Payment Required`	The account is suspended for billing, or a renewal is unpaid. Retrying does not help — settle the balance.
`429 Too Many Requests`	Rate limit reached, or the monthly allowance is spent — retry after the `Retry-After` header.

GET /v1/passepartout/login/status

Returns the current state of a login attempt. Poll this after sending the user to the deep link. While the user hasn't finished, status is pending; once done it becomes completed and carries the access_token and user.

Query Parameters

Parameter	Type	Required	Description
`nonce`	`string`	Yes	The `nonce` returned by Start Login.

Example Request

curl 'https://api.vernesoft.com/v1/passepartout/login/status?nonce=n_9f2c8a1b' \
  -H 'Authorization: Bearer vrn_passepartout_test_123'

Response

{
  "status": "pending"
}

Status Code	Meaning
`200 OK`	Status returned (`pending` or `completed`).
`401 Unauthorized`	Missing or invalid Bearer token.
`404 Not Found`	Unknown or expired `nonce`.

4. Introspect Token

POST /v1/passepartout/tokens/introspect

Validates a Passepartout access token and returns its attributes. Tokens owned by another tenant are reported as { "active": false }.

Request Body

Field	Type	Required	Description
`access_token`	`string`	Yes	The `ppt_live_` token returned by a completed login.

Example Request

curl -X POST https://api.vernesoft.com/v1/passepartout/tokens/introspect \
  -H 'Authorization: Bearer vrn_passepartout_test_123' \
  -H 'Content-Type: application/json' \
  -d '{ "access_token": "ppt_live_7bK2mQ9pXr…" }'

Response

{
  "active": true,
  "subject": "9d3f1c22-4a8e-4b17-9c5e-2f0a1b6d8e44",
  "tenant_id": "b1a7…",
  "scopes": ["passepartout"],
  "expires_at": "2026-07-25T13:00:00Z"
}

Error Format

All errors follow a consistent structure. The SDKs surface these fields as a typed error:

{
  "error": {
    "code": "bot_not_configured",
    "message": "No Telegram bot is configured or enabled for this tenant.",
    "request_id": "req_abc123"
  }
}

Include the request_id when contacting support for faster resolution.