TriportRPC
DashboardDocs

POST /v1/auth/email/start

POSThttps://api.triport.io/v1/auth/email/start

Begins email one-time-password (OTP) login by sending a 6-digit code to the supplied address and returning a `request_id` to use in the verify step.

——5 requests per email address per hour

POST /v1/auth/email/start is the first step of the email OTP login flow for the Triport console. It takes an email address, generates a 6-digit one-time code, emails it to that address, and returns an opaque request_id that ties the subsequent verify call back to this attempt.

The code is valid for 10 minutes. To complete login, pass the returned request_id together with the code the user received to POST /v1/auth/email/verify, which is what actually creates the session.

This endpoint does not require authentication and does not issue a session by itself — it only triggers code delivery. The email is normalized (trimmed and lower-cased) before validation and rate-limiting, so [email protected] and [email protected] count as the same address.

A successful response only confirms that a code was generated and dispatched; it never reveals whether the address belongs to an existing account.

Parameters

Request body

emailstringrequired
The email address to send the login code to. Normalized (trimmed + lower-cased) and validated server-side.

Response

200 OK

request_idstring (UUID)
Identifier for this OTP attempt. Pass it to POST /v1/auth/email/verify along with the code to finish login.

Errors

Errors use the shared error envelope ({ "error": "<code>" }). See errors.md for the full envelope.

CodeHTTPMeaningWhen it happens
invalid_json400Malformed request bodyBody is not valid JSON or exceeds 4 KB.
invalid_email400Email failed validationemail is missing, empty, or not a valid address.
rate_limited429Too many requestsMore than 5 codes requested for the same email within the last hour.
internal500Server errorCode could not be generated, persisted, or delivered.

Examples

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/auth/email/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "[email protected]" }),
});


if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`email start failed: ${error}`);
}


const { request_id } = await res.json();
// Keep request_id; pass it to /v1/auth/email/verify with the user's code.

TypeScript SDK (@triport/sdk)

import { TriportClient } from "@triport/sdk";


const client = new TriportClient();


const { requestId } = await client.auth.emailStart({ email: "[email protected]" });
// Then: await client.auth.emailVerify({ requestId, code });

Python (triport-sdk)

from triport import TriportClient


client = TriportClient()


result = client.auth.email_start(email="[email protected]")
# result.request_id -> pass to client.auth.email_verify(...)

Notes

  • This call starts the flow but never establishes a session. Always follow it with POST /v1/auth/email/verify to obtain the nl_session cookie.
  • Codes expire 10 minutes after they are issued. If a user waits too long, call start again to issue a fresh code.
  • The rate limit is 5 requests per email per hour. There is no daily quota.
  • Other console login flows: Google OAuth and wallet challenge/verify. For an overview of the cookie-session model, see the auth overview.