> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # OAuth 2.1 refresh token rotation > Rotates an opaque refresh token. The previous refresh token is single-use; the response carries a fresh access+refresh pair within the same token family. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml post /oauth/refresh openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: Gitlab - name: Git - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Describe paths: /oauth/refresh: post: tags: - OAuth summary: OAuth 2.1 refresh token rotation description: >- Rotates an opaque refresh token. The previous refresh token is single-use; the response carries a fresh access+refresh pair within the same token family. operationId: OAuthRefresh requestBody: content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/OAuth.RefreshRequest' required: - data type: object required: true responses: '200': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/OAuth.TokenResponse' required: - data type: object description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '422': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Client error '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error security: - {} components: schemas: OAuth.RefreshRequest: additionalProperties: false description: >- Refresh request body. The CLI exchanges a refresh token for a new access+refresh pair when its access token nears expiry. Refresh tokens rotate on every use; a re-presented (already-rotated) refresh token revokes the entire token family server-side and returns INVALID_GRANT. properties: grant_type: description: Always 'refresh_token' for this endpoint. enum: - refresh_token type: string refresh_token: description: >- The opaque refresh token previously issued by /oauth/token or /oauth/refresh. type: string required: - grant_type - refresh_token type: object OAuth.TokenResponse: additionalProperties: false description: >- Token response. The CLI persists access_token + refresh_token; the server only stores their hashes. properties: access_token: description: >- Bearer access token: a signed JWT envelope (HS256, iss='ravion-api') whose payload carries an opaque `token` claim the server uses for authoritative session re-reads on every request, plus a `membership` SessionSnapshot intended for client display only. Clients MUST NOT trust the snapshot fields (user id, email, role, etc.) for authorization decisions; the server re-reads the live record on every call. 24 hour TTL. type: string expires_in: description: Lifetime of access_token in seconds (3600). format: int32 type: integer refresh_token: description: >- Opaque refresh token (43 chars). 30 day TTL, rotated on every /oauth/refresh. type: string token_type: description: Always 'Bearer'. enum: - Bearer type: string required: - access_token - refresh_token - expires_in - token_type type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object securitySchemes: BearerAuth: scheme: Bearer type: http ````