---
title: "Refresh a custodied grant and return a fresh access token"
method: POST
path: "/onprem/v1/oauth/broker/grants/{broker_handle}/refresh"
tags: ["onprem", "__public__"]
---

# Refresh a custodied grant and return a fresh access token

`POST /onprem/v1/oauth/broker/grants/{broker_handle}/refresh`

## Request

- Base URL: `https://api.definite.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.definite.app/onprem/v1/oauth/broker/grants/{broker_handle}/refresh`
- Auth: none declared
- TypeScript: <https://skmtc.dev/definite/apis/defapi/docs/onprem/v1/oauth/broker/grants/:broker_handle/refresh/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `broker_handle` string, required

## Response `200`

Success

- SuccessResponseOAuthBrokerRefreshResponse
  - `success` true, required: Flag for it request was successful
  - `data` OAuthBrokerRefreshResponse, required: POST /onprem/v1/oauth/broker/grants/{handle}/refresh response (contract §2.4). Never carries the refresh token (rotation is persisted central-side).
    - `access_token` string, required
    - `expires_in` integer, required
    - `timestamp` string, date-time, required
    - `broker_handle` string, required
    - `instance_url` string, nullable
    - `client_id` string, nullable: Definite's OAuth client_id for the provider (non-secret). See OAuthBrokerResultResponse.client_id.
  - `meta` ResponseMeta
    - `requestId` string: Unique request identifier for tracing
    - `timestamp` string, date-time: Response timestamp (UTC)
    - `durationMs` integer, nullable: Request processing time in milliseconds

## Other responses

- `401`: Auth Invalid Token
- `403`: Forbidden Insufficient Permissions
- `404`: Resource Not Found
- `409`: Resource Conflict
- `422`: Validation Failed
- `426`: Business Quota Exceeded
- `500`: Internal Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) - [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) - [OpenAPI document](https://skmtc.dev/definite/apis/defapi/revisions/5ea378187147?raw)