OAuth 2.0 Overview

OAuth 2.0 authenticates your application to the MoEngage Public APIs with a short-lived access token instead of an API key sent on every call. You exchange your credentials once for an access token, send that token on your API requests until the token expires, and then refresh the token without sending your API key again. This article covers the end-to-end integration: creating an OAuth 2.0 API key, generating an access token, calling the APIs, and refreshing the access token before the token expires.

Authentication Flow

Stage	Action	Reference
1. Create a key	You create an API key with Authentication Type set to OAuth 2.0.	API Key Dashboard
2. Generate a token	You exchange `client_id` and `client_secret` for an access token and a refresh token.	Generate Access Token
3. Call the APIs	You send the access token in the `Authorization` header as a Bearer token.	Step 3: Call the MoEngage Public APIs
4. Refresh the token	You exchange the refresh token for a new access token before the current access token expires.	Refresh Access Token

The OAuth parameters map to dashboard values as follows:

Parameter	Dashboard Value
`client_id`	The parameter holds your Workspace ID, which the API key dashboard always displays.
`client_secret`	The parameter holds your API key value, which the dashboard displays only once, when you create the key.
`access_token`	The parameter holds a short-lived JWT that you send on every API call. The token stays valid for 5 to 60 minutes, and the default is 15 minutes.
`refresh_token`	The parameter holds a token that you exchange for new access tokens. The token expires after 24 hours without a refresh, and after 30 days at most.

Prerequisites

Before you begin, ensure that you meet the following requirements:

You have access to Settings > Account > API keys in the MoEngage dashboard.
You have identified the data center that hosts your workspace. Your dashboard URL indicates the data center. For more information, refer to Data Centers. If you are unsure which data center hosts your workspace, contact MoEngage Support.

OAuth Base URLs

OAuth requests go to the OAuth host for your data center, and requests to the Public APIs go to your REST API host. Replace {dc} in the examples on this page with your data center number.

Data Center	OAuth Base URL
DC-01	`https://oauth2-01.moengage.com`
DC-02	`https://oauth2-02.moengage.com`
DC-03	`https://oauth2-03.moengage.com`
DC-04	`https://oauth2-04.moengage.com`
DC-05	`https://oauth2-05.moengage.com`
DC-06	`https://oauth2-06.moengage.com`
DC-101	`https://oauth2-101.moengage.com`

Step 1: Create an OAuth 2.0 API Key

Open the API Keys Page

On the left navigation menu in the MoEngage dashboard, go to Settings > Account > API keys.

Open the Create New Key Dialog

Click + Create new key.

Enter a Key Name

Enter a descriptive name in the Key name box, for example orders-integration.

Select the Authentication Type

Under Authentication Type, select OAuth 2.0.

Set the Expiry Time

In the Expiry time (in minutes) box, enter how long each access token stays valid. The value must be between 5 and 60 minutes, and the default is 15 minutes.

Select the API Access

Under Select APIs for access, select the API groups that the key calls. The key accesses only the endpoints that you select in this list.

Save the Key

Click Create key. The dashboard then displays your Workspace ID and the API key value.

Copy the API key immediately. MoEngage displays the API key only once and cannot retrieve the API key afterwards. If you lose the API key, regenerate the key. Regenerating a key invalidates the previous key and every refresh token issued from that key.

The Create new key dialog maps to the OAuth parameters as follows:

Dashboard Field	Use the Field As	Notes
Workspace ID	`client_id`	The dashboard always displays the Workspace ID.
API key	`client_secret`	The dashboard displays the API key only once, when you create the key.
Authentication Type	Not applicable	The value must be OAuth 2.0, or token generation fails with `ER012`.
Select APIs for access	Not applicable	The selection determines which APIs the key calls.
Expiry time (in minutes)	Not applicable	The value must be between 5 and 60 minutes. The default is 15 minutes.

Editing a key’s name, API access, or expiry time revokes the refresh tokens issued from that key, as regenerating the key does. Your next refresh then returns ER010. Generate a new access token as described in Step 2: Generate an Access Token.

To call the Segmentation APIs or Inform, create a Basic Auth key instead. For the API groups that OAuth 2.0 keys support, and for the steps to edit, regenerate, and archive keys, refer to API Key Dashboard.

Step 2: Generate an Access Token

Exchange your client_id and client_secret for an access token and a refresh token. Send the request body in form-encoded format (application/x-www-form-urlencoded). A JSON body returns 415 Unsupported Media Type.

Generate Access Token

curl --request POST \
  --url https://oauth2-{dc}.moengage.com/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_WORKSPACE_ID \
  --data client_secret=YOUR_API_KEY

Store both the access token and the refresh token. The refresh token removes the need to send your API key again for as long as you keep refreshing. To run the request and to review every parameter, response field, and error code, refer to Generate Access Token.

Determine the Token Expiry

The response carries two expiry fields.

Field	Meaning
`expires_in`	The access token’s lifetime in seconds, counted from the moment MoEngage issues the token. Schedule your refresh from this value. The lifetime reflects the Expiry time (in minutes) set on the API key.
`refresh_token_expires_in`	The number of seconds until the refresh token expires if you do not use the token. The value is 24 hours, or less when the refresh token approaches its 30-day limit.

Step 3: Call the MoEngage Public APIs

Send the access token in the Authorization header as a Bearer token.

Call an API with an Access Token

curl --request POST \
  --url https://api-{dc}.moengage.com/v1/customer/YOUR_WORKSPACE_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "customer", "customer_id": "user_12345" }'

For the endpoints that your key can call, refer to API Documentation. For per-endpoint request limits and payload size caps, refer to Rate Limits.

Authentication Errors

When authentication fails, the response carries a MOENGAGE-AUTH-ERROR-CODE header.

HTTP	`MOENGAGE-AUTH-ERROR-CODE`	Cause	Resolution
`401`	`ER008`	The access token has expired.	Refresh the access token. Refer to Step 4: Refresh the Access Token.
`401`	`ER010`	The refresh token that issued this access token has expired or been revoked.	Request a new access token. Refer to Generate Access Token.
`403`	`ER007`	The access token is valid, but the endpoint falls outside the key’s scope.	Add the endpoint to the key’s API access on the dashboard.
`401`	`ER003` or `ER004`	The access token is malformed or altered.	Request a new access token. Refer to Generate Access Token.
`403`	`ER005`	MoEngage could not read the access token’s contents.	Request a new access token. Refer to Generate Access Token.
`401`	`ER022`	The request sent credentials in more than one place.	Send the access token only in the `Authorization` header.

An access token stops working when its refresh token expires, even when expires_in has not run out. Refresh at least once every 24 hours to keep the refresh token alive.

Step 4: Refresh the Access Token

Before the access token expires, exchange the refresh token for a new access token. The refresh request does not use your API key. Send the request body in form-encoded format (application/x-www-form-urlencoded), as in Step 2.

Refresh Access Token

curl --request POST \
  --url https://oauth2-{dc}.moengage.com/v1/oauth/refresh \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data client_id=YOUR_WORKSPACE_ID \
  --data refresh_token=YOUR_REFRESH_TOKEN

A refresh does not issue a new refresh token. Continue using the same refresh token. Each successful refresh keeps that token alive for another 24 hours, up to 30 days from the moment MoEngage issued the token. The refresh_token_expires_in field reports how long the refresh token has left. When the value approaches 0, or when a refresh returns ER010, generate a new access token with your client_id and client_secret.

To run the request and to review every parameter, response field, and error code, refer to Refresh Access Token.

Token Lifecycle

The token endpoint issues both tokens. The refresh endpoint then renews the access token and restarts the refresh token’s 24-hour window, until the refresh token reaches its 30-day limit and you call the token endpoint again.

Token	Lifetime	Renewed By
Access token	The lifetime is between 5 and 60 minutes, and you set the lifetime on the API key. The default is 15 minutes.	Refresh Access Token
Refresh token	The lifetime is 24 hours from the moment MoEngage issues the token or from your last refresh, and 30 days at most.	Generate Access Token

Rate Limits

The token endpoint and the refresh endpoint share the following limits:

Limit	Window
30 requests	Per 10 minutes
5 requests	Per minute

On the token endpoint, both limits apply per client_id and client_secret pair. On the refresh endpoint, 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.

Access tokens are reusable for their full lifetime. Generate one access token and reuse the token until the token approaches expiry. Generating an access token for every API request exceeds the rate limit.

These limits cover the OAuth endpoints only. For the limits and payload size caps on the Public APIs that you call with the access token, refer to Rate Limits.

Recommended Practices

Reuse the access token for its full lifetime. Do not request a new access token for every API call.
Refresh proactively, a few minutes before the access token expires, instead of waiting for an ER008. Use expires_in 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. If your integration stays idle for longer, expect ER010 and generate a new access token.
Handle ER010 as a fallback on both refresh requests and API calls. When either returns ER010, generate a new access token with your client_id and client_secret.
Store the API key securely. Treat the API key as a credential. Do not commit the key to source control or expose the key in client-side code.
Honor Retry-After on a 429 response instead of retrying immediately.

Integration Checklist

Confirm the following points before you move your integration to production:

The OAuth base URL matches your data center.
The OAuth 2.0 API key carries the API access that your integration requires.
Your application stores the Workspace ID and the API key securely.
The token endpoint returns an access token and a refresh token.
A Public API call succeeds with the access token.
Your application reads the token expiry from the expires_in field.
The refresh endpoint returns a new access token.
Your application refreshes the access token before the token expires.
Your application tracks refresh_token_expires_in and refreshes at least once every 24 hours.
The ER010 fallback path, on both refresh requests and API calls, re-authenticates with client_id and client_secret.
Your application honors Retry-After on a 429 response.

Generate Access Token

Request an access token and a refresh token with the client credentials grant.

Refresh Access Token

Exchange a refresh token for a new access token.

API Key Dashboard

Create, scope, edit, regenerate, and archive API keys.

API Documentation

Review the data centers, base URLs, authentication methods, and error handling that apply across the MoEngage REST APIs.

Contact Support

Contact MoEngage Support with your Workspace ID, the endpoint you called, the time of the request in UTC, the HTTP status, and the error_type or MOENGAGE-AUTH-ERROR-CODE from the response. To raise a ticket, refer to Raise a Support Ticket.

Do not include your API key, access token, or refresh token in a support request.

​Authentication Flow

​Prerequisites

​OAuth Base URLs

​Step 1: Create an OAuth 2.0 API Key

​Step 2: Generate an Access Token

​Determine the Token Expiry

​Step 3: Call the MoEngage Public APIs

​Authentication Errors

​Step 4: Refresh the Access Token

​Token Lifecycle

​Rate Limits

​Recommended Practices

​Integration Checklist

​Related Articles

Generate Access Token

Refresh Access Token

API Key Dashboard

API Documentation

​Contact Support

Authentication Flow

Prerequisites

OAuth Base URLs

Step 1: Create an OAuth 2.0 API Key

Step 2: Generate an Access Token

Determine the Token Expiry

Step 3: Call the MoEngage Public APIs

Authentication Errors

Step 4: Refresh the Access Token

Token Lifecycle

Rate Limits

Recommended Practices

Integration Checklist

Related Articles

Contact Support