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

# Refresh a token

> Get new patient tokens from a refresh token, without re-authenticating.

Issues a new patient access token (and rotated refresh token) using the `refresh_token` grant, without requiring the patient to log in again.

See "Keeping the session alive" in the [User Registration](https://openloop.mintlify.site/api-reference/user-registration-guide.md) guide.

**Permissions:** None

**grant\_type** `string` *required*

Must be `refresh_token`.

**refresh\_token** `string` *required*

Refresh token from a previous [Exchange a verification code](https://openloop.mintlify.site/auth/exchange-verification-code.md) or refresh call.

**client\_id** `string` *required*

Must be the same client the refresh token was issued to.

**client\_secret** `string` *required*

Your client secret.

**data** `object` *required*

**data**

**access\_token** `string` *required*

New patient access token.

**token\_type** `string` *required*

Always `Bearer`.

**expires\_in** `integer` *required*

Seconds until the access token expires.

**refresh\_token** `string` *required*

Rotated refresh token — replaces the one used in this request.

**request\_id** `string` *required*

Correlation id echoed on every response.

```bash cURL theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "refresh_token": "<refresh_token>"
  }'
```

```json 200 theme={null}
{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_token": "v1.NGQ4YTk1..."
  },
  "request_id": "1dc1fe12-f80f-408f-86a5-f5604d7568b1"
}
```


## OpenAPI

````yaml POST /auth/token
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /auth/token:
    post:
      tags:
        - Auth
      summary: Obtain or refresh tokens
      description: >-
        Issues tokens for one of three grant types: `client_credentials` for an
        M2M service token, the
        `urn:openloophealth:oauth:grant-type:verification-code` grant to
        exchange a verified OTP for user tokens, and `refresh_token` to refresh
        a user session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthTokenRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >-
            Invalid client credentials, code, or refresh token. Known defect:
            some 401 bodies, such as the one returned for an unregistered
            `client_id`, are not valid JSON. Branch on the HTTP status, not on
            `error.error_code`. If the body does not parse, treat it as plain
            text and pull `request_id` out of it before logging.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Client refused: the client, its organization, or its customer is
            inactive, or the client is not entitled to the requested `audience`.
            Known defect: the body for the `audience` case quotes the
            `client_id` back unescaped and is not valid JSON. If the body does
            not parse, treat it as plain text and pull `request_id` out of it
            before logging, as for the unregistered-client `401`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AuthTokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
      description: >-
        Fields required depend on `grant_type`: `client_credentials` also
        requires `audience`; the verification-code grant also requires `code`;
        `refresh_token` also requires `refresh_token`.
      properties:
        grant_type:
          type: string
          enum:
            - client_credentials
            - urn:openloophealth:oauth:grant-type:verification-code
            - refresh_token
        client_id:
          type: string
        client_secret:
          type: string
        audience:
          type: string
          description: Required for the `client_credentials` grant.
        code:
          type: string
          description: >-
            Verification code from `POST /auth/verify-otp`. Required for the
            verification-code grant.
        refresh_token:
          type: string
          description: Required for the `refresh_token` grant.
    AuthTokenResponse:
      type: object
      required:
        - data
        - request_id
      properties:
        data:
          type: object
          required:
            - access_token
            - token_type
            - expires_in
          properties:
            access_token:
              type: string
            refresh_token:
              type: string
              description: Present for the verification-code and refresh_token grants.
            token_type:
              type: string
              enum:
                - Bearer
            expires_in:
              type: integer
              description: Seconds until the access token expires.
        request_id:
          type: string
          format: uuid
          description: Correlation id echoed on every response.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.