Flowmatic Authentication: JWT Tokens and Refresh Guide

Register, verify your email, and obtain JWT tokens to authenticate every Flowmatic API request via the Authorization: Bearer header.

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.

email · string · required

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

password · string · required

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

fullName · string · required

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

Request

curl -X POST https://api.flowmatic.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "supersecret123",
    "fullName": "Jane Smith"
  }'

Response (201 Created)

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

Error (409 Conflict)

{
  "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.

email · string · required

The email address you registered with.

otp · string · required

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

Request

curl -X POST https://api.flowmatic.io/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "otp": "847291"
  }'

Response (200 OK)

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

Error (400 Bad Request)

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

accessToken · 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.

refreshToken · 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.

email · string · required

The email address associated with the unverified account.

Request

curl -X POST https://api.flowmatic.io/api/auth/resend-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]"
  }'

Response (200 OK)

{
  "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.

email · string · required

Your verified email address.

password · string · required

Your account password.

Request

curl -X POST https://api.flowmatic.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "supersecret123"
  }'

Response (200 OK)

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

Error (401 Unauthorized)

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

accessToken · string

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

refreshToken · 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).

expiresIn · integer

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

tokenType · 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.

refreshToken · string · required

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

Request

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

Response (200 OK)

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

Error (401 Unauthorized)

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

accessToken · string

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

refreshToken · 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:

1. After login, store accessToken, refreshToken, and a calculated expiresAt timestamp (Date.now() + expiresIn * 1000).
2. Before every API request, check if expiresAt is within 60 seconds of the current time.
3. If so, call POST /api/auth/refresh-token first, update both stored tokens and expiresAt, then proceed with the original request.
4. 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.