Authentication

Refresh token

Exchange a refresh token for a new access token without re-authenticating.

POST

https://api.docly.com/v1/auth/refresh

Authorization

curl --request POST \
  --url https://api.yourdomain.com/v1/auth/refresh \
  --header "Authorization: Bearer REFRESH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "device_id": "web-3f92ab1c",
    "rotate_refresh_token": true,
    "client_version": "2.4.1"
  }'

Authorization

curl --request POST \
  --url https://api.yourdomain.com/v1/auth/refresh \
  --header "Authorization: Bearer REFRESH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "device_id": "web-3f92ab1c",
    "rotate_refresh_token": true,
    "client_version": "2.4.1"
  }'

Authorization

curl --request POST \
  --url https://api.yourdomain.com/v1/auth/refresh \
  --header "Authorization: Bearer REFRESH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "device_id": "web-3f92ab1c",
    "rotate_refresh_token": true,
    "client_version": "2.4.1"
  }'

200

401

404

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_29ab8c71e4f9...",
  "expires_at": "2026-03-01T18:25:43Z",
  "session_id": "sess_82bd91fa",
  "refresh_token_expires_at": "2026-06-01T18:25:43Z"
}

200

401

404

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_29ab8c71e4f9...",
  "expires_at": "2026-03-01T18:25:43Z",
  "session_id": "sess_82bd91fa",
  "refresh_token_expires_at": "2026-06-01T18:25:43Z"
}

200

401

404

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_29ab8c71e4f9...",
  "expires_at": "2026-03-01T18:25:43Z",
  "session_id": "sess_82bd91fa",
  "refresh_token_expires_at": "2026-06-01T18:25:43Z"
}

Exchange a valid refresh token for a newly issued access token.

This endpoint allows clients to maintain authenticated sessions without requiring the user to log in again.

Authorizations

Authorization

string

required

A valid refresh token passed using the Bearer authentication scheme.

Format: Authorization: Bearer <refresh_token>

The token must be active and issued by your authentication server.

Authorizations

Authorization

string

required

A valid refresh token passed using the Bearer authentication scheme.

Format: Authorization: Bearer <refresh_token>

The token must be active and issued by your authentication server.

Authorizations

Authorization

string

required

A valid refresh token passed using the Bearer authentication scheme.

Format: Authorization: Bearer <refresh_token>

The token must be active and issued by your authentication server.

Request Body

device_id

string

optional

Unique identifier of the client device requesting the refresh.

Used for session tracking and anomaly detection.

Example: "web-3f92ab1c"

rotate_refresh_token

boolean

optional

Indicates whether a new refresh token should be issued.

Defaults to true.

If set to false, the existing refresh token remains valid.

client_version

string

optional

Version of the client application initiating the request.

Useful for telemetry and debugging.

Example: "2.4.1"

Request Body

device_id

string

optional

Unique identifier of the client device requesting the refresh.

Used for session tracking and anomaly detection.

Example: "web-3f92ab1c"

rotate_refresh_token

boolean

optional

Indicates whether a new refresh token should be issued.

Defaults to true.

If set to false, the existing refresh token remains valid.

client_version

string

optional

Version of the client application initiating the request.

Useful for telemetry and debugging.

Example: "2.4.1"

Request Body

device_id

string

optional

Unique identifier of the client device requesting the refresh.

Used for session tracking and anomaly detection.

Example: "web-3f92ab1c"

rotate_refresh_token

boolean

optional

Indicates whether a new refresh token should be issued.

Defaults to true.

If set to false, the existing refresh token remains valid.

client_version

string

optional

Version of the client application initiating the request.

Useful for telemetry and debugging.

Example: "2.4.1"

Response Fields

access_token

string

required

New short-lived access token used to authorize API requests.

refresh_token

string

required

New refresh token issued when rotation is enabled.

expires_at

string

required

ISO 8601 timestamp indicating when the access token will expire.

Example: "2026-03-01T18:25:43Z"

session_id

string

required

Identifier of the active authentication session.

refresh_token_expires_at

string

optional

Expiration timestamp for the newly issued refresh token.

Response Fields

access_token

string

required

New short-lived access token used to authorize API requests.

refresh_token

string

required

New refresh token issued when rotation is enabled.

expires_at

string

required

ISO 8601 timestamp indicating when the access token will expire.

Example: "2026-03-01T18:25:43Z"

session_id

string

required

Identifier of the active authentication session.

refresh_token_expires_at

string

optional

Expiration timestamp for the newly issued refresh token.

Response Fields

access_token

string

required

New short-lived access token used to authorize API requests.

refresh_token

string

required

New refresh token issued when rotation is enabled.

expires_at

string

required

ISO 8601 timestamp indicating when the access token will expire.

Example: "2026-03-01T18:25:43Z"

session_id

string

required

Identifier of the active authentication session.

refresh_token_expires_at

string

optional

Expiration timestamp for the newly issued refresh token.

Error Fields

error_code

string

required

Machine-readable identifier describing the failure.

Possible values:

refresh_token_invalid
refresh_token_expired
session_not_found
token_rotation_failed

error_description

string

required

Detailed explanation of why the request failed.

Error Fields

error_code

string

required

Machine-readable identifier describing the failure.

Possible values:

refresh_token_invalid
refresh_token_expired
session_not_found
token_rotation_failed

error_description

string

required

Detailed explanation of why the request failed.

Error Fields

error_code

string

required

Machine-readable identifier describing the failure.

Possible values:

refresh_token_invalid
refresh_token_expired
session_not_found
token_rotation_failed

error_description

string

required

Detailed explanation of why the request failed.

Invalidate session

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

Authorization

curl --request POST \
  --url https://api.yourdomain.com/v1/auth/refresh \
  --header "Authorization: Bearer REFRESH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "device_id": "web-3f92ab1c",
    "rotate_refresh_token": true,
    "client_version": "2.4.1"
  }'

200

401

404

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_29ab8c71e4f9...",
  "expires_at": "2026-03-01T18:25:43Z",
  "session_id": "sess_82bd91fa",
  "refresh_token_expires_at": "2026-06-01T18:25:43Z"
}