> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Refresh Access Token > Exchange a refresh token for a new access token. The refresh request does not use your API key. A refresh returns a new access token and does not issue a new refresh token. Continue using the same refresh token. Each successful refresh keeps the refresh token alive for another 24 hours, up to 30 days from the moment MoEngage issued the token. When `refresh_token_expires_in` approaches 0, or when a refresh returns `ER010`, call [Generate Access Token](/api/oauth/generate-access-token) again with your `client_id` and `client_secret`. For the end-to-end integration, refer to [OAuth 2.0 Overview](/api/oauth/oauth-overview). For the recommended refresh timing, refer to [Recommended Practices](/api/oauth/oauth-overview#recommended-practices). #### Rate Limit This endpoint allows 30 requests per 10 minutes and 5 requests per minute. Both limits apply per `client_id` and `refresh_token` pair. A `429` response includes a `Retry-After` header that gives the number of seconds to wait. The same value also appears in the deprecated `X-RETRY-AFTER` header. Read `Retry-After`. Refresh proactively, a few minutes before the access token expires, instead of waiting for an `ER008` on an API call. Use the `expires_in` value returned with the access token to schedule the refresh. Refresh at least once every 24 hours. A refresh token that goes unused for 24 hours expires, and the access tokens issued from that refresh token stop working even when `expires_in` has not run out. ## OpenAPI ````yaml /api/oauth/oauth.yaml post /v1/oauth/refresh openapi: 3.0.3 info: title: MoEngage OAuth 2.0 API version: '1.0' description: >- API for generating and refreshing OAuth 2.0 access tokens used to authenticate requests to the MoEngage Public APIs. You exchange the credentials of an OAuth 2.0 API key for a short-lived access token, send that access token as a Bearer token on your API requests, and refresh the access token before the token expires. For the end-to-end setup, including creating the API key and calling the Public APIs, refer to [OAuth 2.0 Overview](/api/oauth/oauth-overview). servers: - url: https://oauth2-{dc}.moengage.com description: OAuth Endpoint variables: dc: default: '01' enum: - '01' - '02' - '03' - '04' - '05' - '06' - '101' description: >- The 'dc' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of 'dc' in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. security: [] tags: - name: OAuth description: >- Generate and refresh the OAuth 2.0 access tokens that authenticate your MoEngage Public API requests. For the end-to-end integration, refer to [OAuth 2.0 Overview](/api/oauth/oauth-overview). paths: /v1/oauth/refresh: post: tags: - OAuth summary: Refresh Access Token description: >- Exchange a refresh token for a new access token. The refresh request does not use your API key. A refresh returns a new access token and does not issue a new refresh token. Continue using the same refresh token. Each successful refresh keeps the refresh token alive for another 24 hours, up to 30 days from the moment MoEngage issued the token. When `refresh_token_expires_in` approaches 0, or when a refresh returns `ER010`, call [Generate Access Token](/api/oauth/generate-access-token) again with your `client_id` and `client_secret`. For the end-to-end integration, refer to [OAuth 2.0 Overview](/api/oauth/oauth-overview). For the recommended refresh timing, refer to [Recommended Practices](/api/oauth/oauth-overview#recommended-practices). requestBody: required: true description: The form-encoded parameters for the refresh token grant. content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RefreshRequest' example: grant_type: refresh_token client_id: YOUR_WORKSPACE_ID refresh_token: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: >- MoEngage issued a new access token. The response does not carry a new refresh token. The refresh token sent in the request stays valid for another 24 hours, up to 30 days from the moment MoEngage issued the token. content: application/json: schema: $ref: '#/components/schemas/RefreshSuccessResponse' example: access_token: eyJhbGciOiJSUzI1NiJ9.. token_type: Bearer expires_in: 900 refresh_token_expires_in: 86400 '400': description: >- A required form parameter is missing or holds an invalid value. | `error_type` | Cause | Resolution | | --- | --- | --- | | `ER018` | `grant_type` is missing or is not `refresh_token`. | Correct the parameter. | | `ER019` | `client_id` is missing. | Correct the parameter. | | `ER021` | `refresh_token` is missing. | Correct the parameter. | content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' example: status: FAILURE error_type: ER021 reason: refresh_token is required. '401': description: >- MoEngage could not use the refresh token. | `error_type` | Cause | Resolution | | --- | --- | --- | | `ER010` | The refresh token is not valid. The token went unused for 24 hours, passed its 30-day limit, was revoked by a change to the API key, or belongs to another Workspace ID. | Generate a new access token with `client_id` and `client_secret`. | | `ER003` | MoEngage could not read the API key behind the refresh token. | Generate a new access token with `client_id` and `client_secret`. If the error persists, contact MoEngage Support. | content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' example: status: FAILURE error_type: ER010 reason: Refresh token is not valid. '415': description: >- The request body used an unsupported media type. Send the request body in form-encoded format as `application/x-www-form-urlencoded`. content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' '429': description: >- The request exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` response header, and then retry the request. headers: Retry-After: description: The number of seconds to wait before you retry the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' example: status: FAILURE error_type: RATE_LIMIT_EXCEEDED reason: Too many requests. security: [] components: schemas: RefreshRequest: type: object required: - grant_type - client_id - refresh_token properties: grant_type: type: string enum: - refresh_token description: The OAuth 2.0 grant type. The supported value is `refresh_token`. client_id: type: string description: >- Your Workspace ID. The value must match the Workspace ID that the refresh token was issued to, or the request fails with `ER010`. refresh_token: type: string description: >- The refresh token returned by [Generate Access Token](/api/oauth/generate-access-token). The refresh token expires after 24 hours without a refresh, and after 30 days at most. RefreshSuccessResponse: type: object properties: access_token: type: string description: >- The new access token that you send as a Bearer token on your API requests. token_type: type: string description: The token type. The value is always `Bearer`. example: Bearer expires_in: type: integer description: >- The lifetime of the new access token, in seconds. The value reflects the **Expiry time (in minutes)** set on the API key. example: 900 refresh_token_expires_in: type: integer description: >- The number of seconds until the refresh token expires if you do not use the token. Each successful refresh resets the value to 24 hours, or less when the refresh token approaches its 30-day limit. example: 86400 OAuthErrorResponse: type: object properties: status: type: string description: >- The status of the request. The value is `FAILURE` for a failed request. example: FAILURE error_type: type: string description: The MoEngage error code that identifies the cause of the failure. reason: type: string description: A human-readable description of the failure. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.