> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowmaticai.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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.
</Warning>

## Endpoint

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

## Request Body

<ParamField body="refreshToken" type="string" required>
  The refresh token most recently issued to your account — either from a previous [login](/api-reference/auth/login), [email verification](/api-reference/auth/verify-email), 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.
</ParamField>

## Example Request

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl -X POST https://api.flowmatic.io/api/auth/refresh-token \
      -H "Content-Type: application/json" \
      -d '{
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }'
    ```
  </Tab>

  <Tab title="Request Body">
    ```json theme={null}
    {
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c3JfMDEyMzQ1IiwiZW1haWwiOiJhbGljZUBleGFtcGxlLmNvbSIsImlhdCI6MTcxNTAwNzIwMCwiZXhwIjoxNzE1MDEwODAwfQ.newAccessTokenSignature",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c3JfMDEyMzQ1IiwidHlwZSI6InJlZnJlc2giLCJpYXQiOjE3MTUwMDcyMDAsImV4cCI6MTcxNzU5OTIwMH0.newRefreshTokenSignature"
    }
    ```
  </Tab>
</Tabs>

## Response Fields

<ResponseField name="accessToken" type="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.
</ResponseField>

<ResponseField name="refreshToken" type="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.
</ResponseField>

## Using the New Access Token

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

```bash theme={null}
curl https://api.flowmatic.io/api/workflows \
  -H "Authorization: Bearer <new_accessToken>"
```

<Note>
  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](/api-reference/auth/login) to obtain a new token pair.
</Note>

## 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.