Authentication

User-facing authentication uses email and password, JWT access and refresh tokens, and optional device (OAuth-style) flows. These endpoints are used by the web app, CLIs, and native clients.

For REST automation with an API key, see API keys. Send Authorization: Bearer plus your API key on resource requests.

Base URL: https://api.planasonix.com

Session and password flows

string

required

Account email address.

string

required

Account password.

Show Example request and response

curl -X POST https://api.planasonix.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@acme.com","password":"••••••••"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "plnx_rt_01j8k2m4n6p8q0r2s4t6u8v0",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "usr_01hqxyz",
    "email": "alex@acme.com",
    "name": "Alex Rivera",
    "emailVerified": true
  }
}

string

JWT sent as Authorization: Bearer followed by this value for API calls until it expires.

string

Opaque token used with POST /api/auth/refresh to obtain a new access token.

`POST /api/auth/refresh`

Exchange a valid refresh token for a new access token (and optionally a rotated refresh token).

string

required

Refresh token returned from login or a prior refresh.

Show Example request and response

curl -X POST https://api.planasonix.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"plnx_rt_01j8k2m4n6p8q0r2s4t6u8v0"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "plnx_rt_01j9l3n5o7q9r1s3t5u7v9w1",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

`POST /api/register`

Create a new user account (when self-registration is enabled for your workspace).

string

required

Email for the new account.

string

required

Password meeting your organization’s policy.

string

required

Display name.

Show Example request and response

curl -X POST https://api.planasonix.com/api/register \
  -H "Content-Type: application/json" \
  -d '{"email":"jamie@acme.com","password":"••••••••","name":"Jamie Chen"}'

{
  "id": "usr_02hqabc",
  "email": "jamie@acme.com",
  "name": "Jamie Chen",
  "emailVerified": false,
  "message": "Check your inbox to verify your email."
}

`POST /api/forgot-password`

Trigger a password reset email containing a time-limited token.

string

required

Email associated with the account.

Show Example request and response

curl -X POST https://api.planasonix.com/api/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@acme.com"}'

{
  "ok": true,
  "message": "If an account exists for this email, reset instructions have been sent."
}

`POST /api/reset-password`

Complete a password reset using the token from the email.

string

required

Reset token from the email link.

string

required

New password.

Show Example request and response

curl -X POST https://api.planasonix.com/api/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"rst_01j8k2m4n6p8q0r2s4t6u8v0","password":"••••••••"}'

{
  "ok": true,
  "message": "Password updated. You can sign in with your new password."
}

`POST /api/verify-email`

Mark the user’s email as verified using the token from the verification email.

string

required

Verification token from the email link.

Show Example request and response

curl -X POST https://api.planasonix.com/api/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"emv_01j8k2m4n6p8q0r2s4t6u8v0"}'

{
  "ok": true,
  "user": {
    "id": "usr_02hqabc",
    "email": "jamie@acme.com",
    "emailVerified": true
  }
}

Device authorization (v2)

Headless apps (CLI, desktop, TV) use the device code pattern: the user opens a browser, enters a code, and the client polls until authorized.

`POST /api/v2/auth/device`

Start the flow. Returns a device code, user code, and verification URI for the user.

Show Example request and response

curl -X POST https://api.planasonix.com/api/v2/auth/device \
  -H "Content-Type: application/json" \
  -d '{"clientId":"plnx_cli_01hqxyz","scope":"openid profile pipelines:read"}'

{
  "deviceCode": "dev_01j8k2m4n6p8q0r2s4t6u8v0w2x4y6z8",
  "userCode": "WDJB-JQKL",
  "verificationUri": "https://app.planasonix.com/device",
  "verificationUriComplete": "https://app.planasonix.com/device?user_code=WDJB-JQKL",
  "expiresIn": 900,
  "interval": 5
}

integer

Minimum seconds to wait between polling POST /api/v2/auth/device/token.

`POST /api/v2/auth/device/token`

Poll with the deviceCode until the user completes authorization or the code expires.

string

required

deviceCode from the device start response.

string

required

Same client identifier used when starting the device flow.

Show Example responses

Pending (continue polling)

{
  "error": "authorization_pending",
  "error_description": "The user has not yet completed authorization."
}

Success

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "plnx_rt_01j8k2m4n6p8q0r2s4t6u8v0",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

`POST /api/v2/auth/device/authorize`

Browser or authenticated session confirms the userCode and grants the requested scopes to the device client.

string

required

Code shown to the user (for example WDJB-JQKL).

string

Typically the logged-in user’s session or Bearer access token for the approving browser session.

Show Example request and response

curl -X POST https://api.planasonix.com/api/v2/auth/device/authorize \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"userCode":"WDJB-JQKL"}'

{
  "ok": true,
  "clientName": "Planasonix CLI",
  "scopes": ["openid", "profile", "pipelines:read"]
}

Using tokens on the REST API

GET /api/pipelines HTTP/1.1
Host: api.planasonix.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

GET /api/pipelines HTTP/1.1
Host: api.planasonix.com
Authorization: Bearer plnx_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Credential	Typical use
JWT access token	Interactive apps after login or device flow
API key	Servers, CI, and long-lived integrations

Treat refresh tokens like passwords: store them in the OS keychain or a secret manager, not in source control.

Overview

Data platform

Orchestration

Integration

Governance

Iceberg Catalog

Platform

Session and password flows

`POST /api/auth/refresh`

`POST /api/register`

`POST /api/forgot-password`

`POST /api/reset-password`

`POST /api/verify-email`

Device authorization (v2)

`POST /api/v2/auth/device`

`POST /api/v2/auth/device/token`

`POST /api/v2/auth/device/authorize`

Using tokens on the REST API

​Session and password flows

​POST /api/login

​POST /api/auth/refresh

​POST /api/register

​POST /api/forgot-password

​POST /api/reset-password

​POST /api/verify-email

​Device authorization (v2)

​POST /api/v2/auth/device

​POST /api/v2/auth/device/token

​POST /api/v2/auth/device/authorize

​Using tokens on the REST API

Session and password flows

`POST /api/login`

`POST /api/auth/refresh`

`POST /api/register`

`POST /api/forgot-password`

`POST /api/reset-password`

`POST /api/verify-email`

Device authorization (v2)

`POST /api/v2/auth/device`

`POST /api/v2/auth/device/token`

`POST /api/v2/auth/device/authorize`

Using tokens on the REST API