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.comSession and password flows POST /api/loginSign in with email and password. Returns short-lived access and long-lived refresh tokens.
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 } }
JWT sent as Authorization: Bearer followed by this value for API calls until it expires.
Opaque token used with POST /api/auth/refresh to obtain a new access token.
POST /api/auth/refreshExchange a valid refresh token for a new access token (and optionally a rotated refresh token).
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/registerCreate a new user account (when self-registration is enabled for your workspace).
Email for the new account.
Password meeting your organization’s policy.
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-passwordTrigger a password reset email containing a time-limited token.
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-passwordComplete a password reset using the token from the email.
Reset token from the email link.
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-emailMark the user’s email as verified using the token from the verification email.
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/deviceStart 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 }
Minimum seconds to wait between polling POST /api/v2/auth/device/token.
POST /api/v2/auth/device/tokenPoll with the deviceCode until the user completes authorization or the code expires.
deviceCode from the device start response.
Same client identifier used when starting the device flow.
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/authorizeBrowser or authenticated session confirms the userCode and grants the requested scopes to the device client.
Code shown to the user (for example WDJB-JQKL).
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 Access token
API key (automation)
GET /api/pipelines HTTP / 1.1 Host : api.planasonix.com Authorization : Bearer eyJhbGciOiJIUzI1NiIs... 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.
