Skip to content

🚀 Quick Start Guide

Onboarding & Prerequisites

Getting started requires a short onboarding step with the Earth Miles team, followed by some setup on your end.

What Earth Miles Sets Up for You

Before you can begin integrating, reach out to the Earth Miles team. We will:

  • Create your Account – Register you as an official partner in our system
  • Issue your Client Credentials – Provide your client_id and client_secret
  • Assign your Keyword – Create a unique keyword tied to your partner account and add it to our system; you must include this keyword in all transactions
  • Provide your Membership ID – Used to identify your program within the platform

What You Need to Have Ready

Before starting the integration, make sure you have the following in place:

  • Redirect URI – A registered callback URL in your application where users will be redirected after authorization
    • Examples: https://myapp.com/callback/earthmiles or myapp://earthmiles-callback
  • Server-side Environment – A backend application capable of securely storing credentials and handling token exchange
  • OAuth Scopes – Understand which scopes your integration requires:
    • miles:read – Read user miles balance and info
    • miles:write – Award points and process transactions

How to Integrate

1. Set Up OAuth Flow

Redirect users to our authorization endpoint with these parameters:

GET https://auth.earthmiles.app/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK_URL&
  scope=miles:read%20miles:write&
  language=en&
  state=RANDOM_STATE&
  response_type=code&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

2. Handle the Callback

After the user is redirected to your application, get the authorization code and exchange it for the access tokens:

curl -X POST https://backend.earthmiles.app/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code_verifier": "CODE_VERIFIER"
  }'

3. Award Points

Use the access token to award miles:

curl -X POST https://backend.earthmiles.app/api/partner-api/award-points \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "categoryId": "your_category_id",
    "pointsToAward": 100
  }'