Authentication

All requests to the MeWe API require prior authentication.

MeWe supports authentication for both Embedded apps inside MeWe and Standalone apps. Each method firstly gets loginRequestToken which is then exchanged for the apiToken used for all subsequent API requests. Where those methods differ is how the loginRequestToken is obtained.

Embedded Apps

Embedded apps use a simplified authentication flow. Users consent to the permissions required by the application within MeWe before launching the app. This method doesn't require collecting user credentials or any additional steps.

Step 1: Request a Login Token

Your embedded app needs to obtain a loginRequestToken in order to exchange it for an apiToken. For embedded apps, this is handled via postMessage communication between MeWe and your application.

During the app initialisation it should send an CLIENT_HANDSHAKE_REQUEST message and listen for the HOST_HANDSHAKE_RESPONSE that will contain loginRequestToken:

// Sending the auth token request
window.parent.postMessage({ type: 'CLIENT_HANDSHAKE_REQUEST' }, '*');

// Listening for the response
function handler(event) {
  const { type, loginRequestToken } = event.data;

  if (type === 'HOST_HANDSHAKE_RESPONSE' && loginRequestToken) {
    window.removeEventListener('message', handler);
    resolve({ loginRequestToken });
  }
}
window.addEventListener('message', handler);

Step 2: Exchange Token for API Token

Once you receive the loginRequestToken, exchange it for an apiToken:

curl -X GET "MEWE_HOST/api/dev/token?loginRequestToken=LOGIN_REQUEST_TOKEN" \
  -H "X-App-Id: YOUR_APP_ID"

// response
{
  "expiresAt": "2025-03-30T21:07:40.253Z",
  "apiToken": "string"
}

After a successful token exchange, your application can make authenticated requests to the MeWe API until the token expires. Once expired, repeat this authentication flow to obtain a new token.

Standalone Apps - OAuth

MeWe provides any standalone app with the OAuth 2.0 Implicit Grant authorization method. It requires redirecting user to MeWe login page with proper callback URL that will handle the outcome of authorization. In this flow the loginRequestToken is delivered via URL params and then must be exchanged for an apiToken like in any other MeWe authentication method.

Step 1: Redirect to MeWe Login

Redirect users to the MeWe login page with your app credentials:

MEWE_HOST/login?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}

Request Parameters

Step 2: Handle the Redirect Response

After the user authorizes your app, they are redirected to your redirect_uri with parameters in the URL query string.

Success Response

https://yourapp.com/callback?loginRequestToken=abc123&state=xyz789

Error Response

https://yourapp.com/callback?error=access_denied&errorDescription=The+user+denied+the+request&state=xyz789

Step 3: Extract the Login Request Token

Your server or client-side JavaScript can read the URL query parameters to extract the token:

// Parse the URL query string to extract the token
const params = new URLSearchParams(window.location.search);

const loginRequestToken = params.get('loginRequestToken');
const state = params.get('state');
const error = params.get('error');

if (error) {
  const errorDescription = params.get('errorDescription');
  console.error('OAuth error:', error, errorDescription);
} else if (loginRequestToken) {
  // Verify the state matches what you sent
  if (state !== expectedState) {
    console.error('State mismatch - possible CSRF attack');
  } else {
    // Proceed to exchange loginRequestToken for apiToken
    console.log('Login request token received, exchanging for API token...');
  }
}

Step 4: Exchange Token for API Token

Once you have the loginRequestToken, exchange it for an apiToken:

curl -X GET "MEWE_HOST/api/dev/token?loginRequestToken=LOGIN_REQUEST_TOKEN" \
  -H "X-App-Id: YOUR_APP_ID"

// response
{
  "expiresAt": "2025-03-30T21:07:40.253Z",
  "apiToken": "string"
}

After a successful token exchange, your application can make authenticated requests to the MeWe API until the token expires. Once expired, repeat this authentication flow to obtain a new token.

Security Recommendations

1. Always use the state parameter - Generate a random value, store it before redirect, and verify it matches on callback to prevent CSRF attacks.
2. Use HTTPS for your redirect_uri to ensure tokens are transmitted securely.
3. Store tokens securely - Never expose tokens in URLs or logs after extraction.
4. Validate the redirect_uri on your server matches expected values.

Standalone Apps - In-App Request

In-App Request method requires users to approve your application's access request through the MeWe app. Your app needs to collect user's login identifier and use it to generate this request inside MeWe as a simple notification. This request will also generate and return the loginRequestToken which can be exchanged for the apiToken after request is approved by the user.

Step 1: Request a loginRequestToken

Your application must collect the user's email address or phone number (the identifier they use to sign in to MeWe) and request a loginRequestToken using the following endpoint:

curl -X POST MEWE_HOST/api/dev/signin \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"email/phone"}'

// response
{ "loginRequestToken" : "string" }

Step 2: Exchange Token for API Token

Once you have the loginRequestToken, exchange it for an apiToken:

curl -X GET "MEWE_HOST/api/dev/token?loginRequestToken=LOGIN_REQUEST_TOKEN" \
  -H "X-App-Id: YOUR_APP_ID"

// response
{
  "pending": true,
  "expiresAt": "2025-03-30T21:07:40.253Z",
  "apiToken": "string"
}

After a successful token exchange, your application can make authenticated requests to the MeWe API until the token expires. Once expired, you will need to repeat this authentication flow to obtain a new token.