Flowmatic Authentication: JWT Tokens and Refresh Guide

Every Flowmatic API request — except the registration, verification, and login endpoints themselves — requires a valid JSON Web Token (JWT) passed in the Authorization header. This guide covers the complete authentication lifecycle: creating your account, verifying your email, obtaining tokens, using them in requests, and refreshing them before they expire. Follow these steps once to bootstrap your integration, then automate token refresh so your application never has to ask users to log in again.

Never hard-code your accessToken or refreshToken in source code, client-side JavaScript, or public repositories. Store tokens in environment variables, a secrets manager, or a secure server-side session store. Treat them with the same care as passwords.

Step 1 — Register an Account

Send a POST request to /api/auth/register to create a new Flowmatic account. On success, Flowmatic sends an OTP (one-time passcode) to the email address you provide. You will need this OTP to verify your email in the next step.

string

required

The email address for your new account. Must be a valid, deliverable address — this is where OTPs and workflow notifications are sent.

string

required

Your chosen password. Minimum 8 characters. Flowmatic stores your password securely and never exposes it after account creation.

string

required

Your full name. Displayed in the dashboard and included in account-level emails.

Request
Response (201 Created)
Error (409 Conflict)

curl -X POST https://api.flowmatic.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "supersecret123",
    "fullName": "Jane Smith"
  }'

{
  "message": "Registration successful. Please check your email for a verification code."
}

{
  "error": "EMAIL_ALREADY_REGISTERED",
  "message": "An account with this email address already exists."
}

If you already have an account and just need a new OTP, skip to Resend OTP below. Do not register again — duplicate registration attempts return a 409 error.

Step 2 — Verify Your Email Address

After registration, Flowmatic locks the account until the email address is confirmed. Submit the OTP from your inbox to unlock it. On success, Flowmatic immediately returns an accessToken and a refreshToken — you can start making authenticated requests without a separate login call. OTPs are single-use and expire after 10 minutes.

string

required

The email address you registered with.

string

required

The six-digit code delivered to your inbox after registration (or after a resend request).

Request
Response (200 OK)
Error (400 Bad Request)

curl -X POST https://api.flowmatic.io/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "otp": "847291"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDFoeC4uLiIsImV4cCI6MTcxNTM0NTYwMH0.abc123",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4gZXhhbXBsZQ=="
}

{
  "error": "INVALID_OR_EXPIRED_OTP",
  "message": "The verification code is invalid or has expired. Please request a new one."
}

string

A signed JWT used to authenticate API requests. Include it in the Authorization: Bearer header. Use POST /api/auth/login to check the expiresIn value, or refresh proactively before it expires.

string

A long-lived token used to request new access tokens via POST /api/auth/refresh-token without re-entering credentials.

Resend OTP

If your OTP expired or never arrived, request a fresh one. Flowmatic invalidates any previously issued OTP before sending the new one, so only the latest code is valid.

string

required

The email address associated with the unverified account.

Request
Response (200 OK)

curl -X POST https://api.flowmatic.io/api/auth/resend-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com"
  }'

{
  "message": "A new verification code has been sent to your email address."
}

Resend requests are rate-limited. If you trigger this endpoint too frequently, you will receive a 429 Too Many Requests response. Wait at least 60 seconds between resend attempts.

Step 3 — Log In

For any session after your initial verification, use POST /api/auth/login to exchange your credentials for a fresh JWT accessToken and a refreshToken. Both are required for a complete integration — the accessToken authenticates your API calls, and the refreshToken lets you obtain a new accessToken without asking the user to re-enter their password.

string

required

Your verified email address.

string

required

Your account password.

Request
Response (200 OK)
Error (401 Unauthorized)

curl -X POST https://api.flowmatic.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "supersecret123"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDFoeC4uLiIsImV4cCI6MTcxNTM0NTYwMH0.abc123",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4gZXhhbXBsZQ==",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

{
  "error": "INVALID_CREDENTIALS",
  "message": "The email or password you entered is incorrect."
}

string

A signed JWT used to authenticate API requests. Include it in the Authorization: Bearer header. Expires after expiresIn seconds.

string

A long-lived token used to request new access tokens. Does not expire on a fixed schedule but is invalidated when you call the logout endpoint or refresh it (single-use).

integer

The number of seconds until the accessToken expires. Typically 3600 (one hour).

string

Always "Bearer". This is the authentication scheme you must use in the Authorization header.

The refreshToken is single-use. Once you exchange it for a new accessToken, the old refreshToken is invalidated and a fresh one is issued. Always persist the latest refreshToken returned by /api/auth/refresh-token.

Step 4 — Authenticate Requests

With your accessToken in hand, add it to every API request using the standard HTTP Authorization header:

Authorization: Bearer <accessToken>

Here is an example of an authenticated request to list your workflows:

curl -X GET https://api.flowmatic.io/api/workflows \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

If you omit the header or supply an expired token, Flowmatic returns 401 Unauthorized:

{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid Authorization header. Please provide a valid Bearer token."
}

The Authorization header is case-insensitive for the header name but the scheme must be exactly Bearer (capital B). Most HTTP clients handle this automatically.

Step 5 — Refresh Your Access Token

Access tokens expire after expiresIn seconds (typically one hour). Rather than asking users to log in again, exchange your refreshToken for a new pair of tokens using POST /api/auth/refresh-token.

string

required

The refreshToken received from your most recent login or token-refresh call. This token is invalidated once used.

Request
Response (200 OK)
Error (401 Unauthorized)

curl -X POST https://api.flowmatic.io/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4gZXhhbXBsZQ=="
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDFoeC4uLiIsImV4cCI6MTcxNTM0OTIwMH0.xyz789",
  "refreshToken": "bmV3IHJlZnJlc2ggdG9rZW4gZ2VuZXJhdGVk",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

{
  "error": "INVALID_REFRESH_TOKEN",
  "message": "The refresh token is invalid, expired, or has already been used."
}

string

Your new access token. Replace the previous value in your token store immediately.

string

A new refresh token. Persist this and discard the old one — the old token is now invalid.

Token Expiry and Refresh Strategy

Understanding when and how to refresh keeps your integration running smoothly without unnecessary re-authentication prompts.

Token	Typical Lifetime	When to Refresh
`accessToken`	1 hour (`expiresIn` seconds)	When a request returns `401`, or proactively before expiry
`refreshToken`	Long-lived (days to weeks)	After each use — a new one is always issued on refresh

Recommended approach for server-side integrations:

After login, store accessToken, refreshToken, and a calculated expiresAt timestamp (Date.now() + expiresIn * 1000).
Before every API request, check if expiresAt is within 60 seconds of the current time.
If so, call POST /api/auth/refresh-token first, update both stored tokens and expiresAt, then proceed with the original request.
If a request still returns 401 after a refresh (rare, but possible if the refresh token was also invalidated), fall back to prompting for credentials.

# Example: check current token validity, then refresh if needed
# (pseudo-bash for illustration)

EXPIRES_AT=1715345600   # stored from login
NOW=$(date +%s)

if [ $((EXPIRES_AT - NOW)) -lt 60 ]; then
  echo "Token expiring soon — refreshing..."
  curl -X POST https://api.flowmatic.io/api/auth/refresh-token \
    -H "Content-Type: application/json" \
    -d '{ "refreshToken": "'$REFRESH_TOKEN'" }'
fi

If your refreshToken is compromised, an attacker can silently obtain new accessTokens indefinitely. Immediately log out all sessions from the Flowmatic dashboard under Account → Security → Revoke All Sessions to invalidate all outstanding refresh tokens.

Authentication Endpoint Summary

Method	Endpoint	Auth Required	Purpose
`POST`	`/api/auth/register`	No	Create a new account
`POST`	`/api/auth/verify-email`	No	Confirm email with OTP
`POST`	`/api/auth/resend-otp`	No	Re-send a verification OTP
`POST`	`/api/auth/login`	No	Obtain access + refresh tokens
`POST`	`/api/auth/refresh-token`	No	Exchange refresh token for new tokens

All other Flowmatic endpoints require Authorization: Bearer <accessToken>.

Looking for a complete walkthrough that ties authentication into a real workflow? See the Quickstart guide — it covers every step from registration through to monitoring a live run.

Get Started

Core Concepts

Guides

Flowmatic Authentication: JWT Tokens and Refresh Guide

Step 1 — Register an Account

Step 2 — Verify Your Email Address

Resend OTP

Step 3 — Log In

Step 4 — Authenticate Requests

Step 5 — Refresh Your Access Token

Token Expiry and Refresh Strategy

Authentication Endpoint Summary

​Step 1 — Register an Account

​Step 2 — Verify Your Email Address

​Resend OTP

​Step 3 — Log In

​Step 4 — Authenticate Requests

​Step 5 — Refresh Your Access Token

​Token Expiry and Refresh Strategy

​Authentication Endpoint Summary

Step 1 — Register an Account

Step 2 — Verify Your Email Address

Resend OTP

Step 3 — Log In

Step 4 — Authenticate Requests

Step 5 — Refresh Your Access Token

Token Expiry and Refresh Strategy

Authentication Endpoint Summary