Quickstart: REST API

Prerequisites

• Any HTTP client (fetch, axios, curl)
• A Rakomi API key (starts with akm_live_ or akm_test_)

Authentication

All API requests require an API key passed in the X-API-Key header:

curl -H "X-API-Key: akm_test_xxx" https://api.rakomi.com/v1/health

1. Register a user

   curl -X POST https://api.rakomi.com/v1/auth/register \
     -H "X-API-Key: akm_test_xxx" \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com", "password": "SecureP@ss123"}'

   Response (201):

   {
     "user_id": "01926f1a-...",
     "email": "user@example.com",
     "email_verified": false,
     "created_at": "2026-03-03T12:00:00.000Z"
   }

2. Log in

   curl -X POST https://api.rakomi.com/v1/auth/login \
     -H "X-API-Key: akm_test_xxx" \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com", "password": "SecureP@ss123"}'

   Response (200):

   {
     "access_token": "eyJhbGciOiJSUzI1NiIs...",
     "refresh_token": "rt_01926f1b-...",
     "token_type": "Bearer",
     "expires_in": 900
   }

3. Access protected resources

   curl https://api.rakomi.com/v1/auth/me \
     -H "X-API-Key: akm_test_xxx" \
     -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

4. Verify JWTs via JWKS

   Rakomi publishes its public keys at /.well-known/jwks.json. Use this to verify tokens server-side without calling the API.

   curl https://api.rakomi.com/.well-known/jwks.json

Framework examples

Nuxt

server/middleware/auth.ts

import * as jose from 'jose';

const JWKS = jose.createRemoteJWKSet(
  new URL('https://api.rakomi.com/.well-known/jwks.json'),
);

export default defineEventHandler(async (event) => {
  const token = getHeader(event, 'authorization')?.slice(7);
  if (!token) throw createError({ statusCode: 401 });

  try {
    const { payload } = await jose.jwtVerify(token, JWKS, {
      algorithms: ['RS256'],
      issuer: 'rakomi.com',
    });
    event.context.auth = payload;
  } catch {
    throw createError({ statusCode: 401 });
  }
});

SvelteKit

src/hooks.server.ts

import * as jose from 'jose';
import type { Handle } from '@sveltejs/kit';

const JWKS = jose.createRemoteJWKSet(
  new URL('https://api.rakomi.com/.well-known/jwks.json'),
);

export const handle: Handle = async ({ event, resolve }) => {
  const token = event.request.headers.get('authorization')?.slice(7);
  if (token) {
    try {
      const { payload } = await jose.jwtVerify(token, JWKS, {
        algorithms: ['RS256'],
        issuer: 'rakomi.com',
      });
      event.locals.auth = payload;
    } catch {
      // Token invalid — continue without auth
    }
  }
  return resolve(event);
};

Remix

app/utils/auth.server.ts

import * as jose from 'jose';

const JWKS = jose.createRemoteJWKSet(
  new URL('https://api.rakomi.com/.well-known/jwks.json'),
);

export async function requireAuth(request: Request) {
  const token = request.headers.get('authorization')?.slice(7);
  if (!token) throw new Response('Unauthorized', { status: 401 });

  try {
    const { payload } = await jose.jwtVerify(token, JWKS, {
      algorithms: ['RS256'],
      issuer: 'rakomi.com',
    });
    return payload;
  } catch {
    throw new Response('Unauthorized', { status: 401 });
  }
}

API endpoints

Method	Path	Description
GET	/v1/health	Health check
GET	/.well-known/jwks.json	Public signing keys (JWKS)
POST	/v1/auth/register	Register new user
POST	/v1/auth/login	Login and get tokens
POST	/v1/auth/refresh	Refresh access token
POST	/v1/auth/logout	Logout (revoke session)
GET	/v1/auth/me	Get current user profile
DELETE	/v1/auth/me/sessions/{id}	Revoke specific session
POST	/v1/auth/verify-email	Verify email address
POST	/v1/auth/resend-verification	Resend verification email
POST	/v1/auth/forgot-password	Request password reset
POST	/v1/auth/reset-password	Reset password with token
POST	/v1/auth/change-password	Change password (authenticated)

For full details including request/response schemas, see the interactive API Reference.