DocsOAuth Integration

KOOMPI OAuth Documentation

Complete guide to integrating KOOMPI OAuth authentication into your application.

Quick Start

Get up and running with KOOMPI OAuth in under 5 minutes.

1

Create Project

Get your credentials

2

Add Redirect URI

Whitelist your callback

3

Integrate

Add the login button

Add login button
html
<a href="https://oauth.koompi.org/v2/oauth?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL">
  <button>Login with KOOMPI</button>
</a>

Prerequisites

What you need before integrating KOOMPI OAuth.

OAuth Credentials

A project with client_id and client_secret from the dashboard.

Redirect URI

At least one whitelisted callback URL (e.g., http://localhost:3000/callback).

Backend Server

A secure server to handle the token exchange (never expose secrets client-side).

Security Warning

Never expose your client_secret in client-side code, source control, or public repositories.

Dashboard Setup

Create and configure your OAuth project.

  1. 1Sign in at dash.koompi.org
  2. 2Click 'New Project' and enter your application name
  3. 3Add your redirect URIs (must match exactly what you'll use)
  4. 4Enable authentication providers (Google, Apple, Telegram, Email)
  5. 5Copy your client_id and client_secret

Authorization Flow

Redirect users to KOOMPI for authentication.

Your frontend redirects users to the KOOMPI OAuth endpoint. After authentication, KOOMPI redirects back to your redirect_uri with an authorization code.

Authorization Endpoint
url
https://oauth.koompi.org/v2/oauth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=profile.basic profile.contact
  &state=RANDOM_STATE_STRING

Available Scopes

ScopeDescription
profile.basicBasic identity (default)
profile.contactContact information
wallet.readPublic wallet details
wallet.transferTransfer ERC20 tokens on user's behalf
wallet.balanceRead token balances from user's wallet

Token Exchange

Exchange the authorization code for an access token and user data.

When KOOMPI redirects to your callback, extract the code parameter and exchange it for an access token and user data on your backend.

POST /v2/oauth/token
http
POST https://oauth.koompi.org/v2/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "redirect_uri": "<your_redirect_uri>"
}
Response (includes user data!)
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "profile.basic profile.contact",
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "fullname": "John Doe",
    "email": "john@example.com",
    "wallet_address": "0x..."
  }
}

Simplified Flow: The token response now includes user data, so you don't need a separate call to /userinfo!

Important: This exchange must happen server-side. Never send yourclient_secret from the browser.

Fetch User Info (Optional)

Retrieve user profile data if you need to refresh it later.

The /token endpoint already returns user data. Use this endpoint only if you need to refresh user info later.

GET /v2/oauth/userinfo
http
GET https://oauth.koompi.org/v2/oauth/userinfo
Authorization: Bearer <access_token>
Accept: application/json
Response
json
{
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "fullname": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "profile": "https://...",
    "wallet_address": "0x...",
    "telegram_id": 123456789,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "status": "success"
}

Fields returned depend on the scopes you requested during authorization.

Refresh Token

Renew access tokens without re-authentication.

Access tokens expire after 1 hour. Use the refresh token to get a new access token without requiring user re-authentication.

POST /v2/oauth/refresh
http
POST https://oauth.koompi.org/v2/oauth/refresh
Content-Type: application/json

{
  "refresh_token": "<your_refresh_token>",
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>"
}
Response
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "NEW_REFRESH_TOKEN",
  "expires_in": 3600,
  "refresh_token_expires_in": 31536000,
  "scope": "profile.basic wallet.transfer"
}

Note: Refresh tokens are rotated on each use. Store the new refresh_token from the response for future requests.

ERC20 API

Transfer tokens on behalf of users with wallet.transfer scope.

With the wallet.transfer scope, your app can transfer ERC20 tokens on behalf of authenticated users.

POST /v2/erc20/transfer
http
POST https://oauth.koompi.org/v2/erc20/transfer
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "to_address": "0x...",
  "token_address": "0x...",
  "amount": "1000000000000000000"
}
EndpointAuthDescription
/v2/erc20/balanceNoneGet token balance
/v2/erc20/transferOAuth (wallet.transfer)Transfer tokens on user's behalf

ERC1155 (NFT) API

Mint and transfer NFTs using project API key.

NFT operations require your project's client_secret as an API key. Pass it via the X-API-Key header.

POST /v2/erc1155/mint
http
POST https://oauth.koompi.org/v2/erc1155/mint
X-API-Key: <your_client_secret>
Content-Type: application/json

{
  "to_address": "0x...",
  "token_id": 1,
  "amount": 1,
  "metadata_uri": "ipfs://..."
}
EndpointDescription
/v2/erc1155/mintMint NFT to address
/v2/erc1155/burnBurn NFT

JavaScript SDK

Simplify integration with the official npm package.

Use the official SDK to simplify OAuth integration in JavaScript/TypeScript projects. It includes built-in PKCE support and handles state management automatically.

Installation
bash
npm install @koompi/oauth
Frontend (Browser)
typescript
import { KoompiAuth } from '@koompi/oauth';

const auth = new KoompiAuth({
  clientId: process.env.NEXT_PUBLIC_KOOMPI_CLIENT_ID!,
  redirectUri: 'https://your-app.com/callback',
});

// createLoginUrl() is async - generates PKCE automatically
const authorizeUrl = await auth.createLoginUrl({
  scope: ['profile.basic', 'profile.contact'],
});

window.location.href = authorizeUrl;
Backend (Server)
typescript
import { KoompiAuth } from '@koompi/oauth';

const auth = new KoompiAuth({
  clientId: process.env.KOOMPI_CLIENT_ID!,
  clientSecret: process.env.KOOMPI_CLIENT_SECRET!,
  redirectUri: 'https://your-app.com/callback',
});

// Exchange code for token
const token = await auth.exchangeCode({ code, state });

// Fetch user info
const user = await auth.getUserInfo(token.access_token);
View on npm

Complete Flow Overview

End-to-end authentication sequence diagram.

1

User clicks login

Frontend redirects to KOOMPI OAuth

2

User authenticates

KOOMPI handles login (email, Google, etc.)

3

Callback received

KOOMPI redirects with ?code=...

4

Token exchange

Backend POSTs to /v2/oauth/token

5

Get user info

Backend calls /v2/oauth/userinfo

6

Create session

Issue your own JWT/cookie to the user