POST /api/auth/refresh-token — Refresh Your Access Token

POST /api/auth/refresh-token — Exchange a valid refresh token for a new access token and refresh token pair when your current access token expires.

Flowmatic access tokens are short-lived by design to limit exposure if a token is ever compromised. When your accessToken expires, rather than asking you to log in again, you can exchange your refreshToken for a brand-new accessToken and refreshToken pair. This endpoint supports seamless token rotation — both tokens are replaced on every call, so you should always store and use the latest values returned.

Flowmatic uses rotating refresh tokens. Every time you call this endpoint, the refresh token you submitted is immediately invalidated, and a new refreshToken is returned alongside the new accessToken. If you attempt to reuse an old refresh token, the request will be rejected. Always replace your stored refreshToken with the value returned in each response.

Endpoint

POST https://api.flowmatic.io/api/auth/refresh-token

Request Body

refreshToken · string · required

The refresh token most recently issued to your account — either from a previous login, email verification, or a prior call to this endpoint. This value is a signed JWT and must be submitted exactly as received. It is invalidated as soon as this request is processed successfully.

Example Request

Request

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

Request Body

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c3JfMDEyMzQ1IiwiZW1haWwiOiJhbGljZUBleGFtcGxlLmNvbSIsImlhdCI6MTcxNTAwNzIwMCwiZXhwIjoxNzE1MDEwODAwfQ.newAccessTokenSignature",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c3JfMDEyMzQ1IiwidHlwZSI6InJlZnJlc2giLCJpYXQiOjE3MTUwMDcyMDAsImV4cCI6MTcxNzU5OTIwMH0.newRefreshTokenSignature"
}

Response Fields

accessToken · string

A new short-lived JWT for authenticating API requests. Replace your previously stored accessToken with this value immediately. Pass it as a Bearer token in the Authorization header of all subsequent Flowmatic API calls.

refreshToken · string

A new long-lived refresh token that replaces the one you submitted in the request body. Store this securely and discard the old value — the previous refresh token is now permanently invalidated and cannot be reused.

Using the New Access Token

After a successful token refresh, use your new accessToken in the Authorization header just as you did before:

curl https://api.flowmatic.io/api/workflows \
  -H "Authorization: Bearer <new_accessToken>"

If your refreshToken itself has expired (refresh tokens are long-lived but not indefinite), you will need to re-authenticate using POST /api/auth/login to obtain a new token pair.

Token Rotation Best Practices

• Always persist the latest tokens. After every call to this endpoint, overwrite both your stored accessToken and refreshToken with the freshly issued values.
• Refresh proactively. Rather than waiting for a request to fail with a 401 Unauthorized error, check the exp claim in your accessToken JWT and refresh before it expires to avoid interruptions to your workflows.
• Never share tokens. Treat both tokens as secrets equivalent to a password. Store them in environment variables, a secrets manager, or an encrypted store — never in source code or logs.