@ariary/auth

Authentication SDK for the Ariari platform. Works like Firebase Auth — create an app, get a secret, and your users authenticate via REST.

Mobile / client-side safe — appSecret is designed to live in your app or frontend. Admin operations (user management) require an idToken obtained from a signed-in admin user and are meant for server-side use.

Install

yarn add @ariary/auth

Get your credentials

1. Sign in at ariari.mg
2. Create a project — you'll get a projectId
3. Create an AriariAuth app to get your appSecret (Ar-Auth_...)
4. Configure your providers (email, phone, Google, etc.) from your dashboard

Setup

import AriariAuth from '@ariary/auth'

AriariAuth.config({
  appSecret: 'Ar-Auth_...',
})

Pass projectId if you need admin operations (user management):

AriariAuth.config({
  appSecret: 'Ar-Auth_...',
  projectId: 'Ar-Prj_...',
})

Email / Password

Sign up

await AriariAuth.signUp({
  email: '[email protected]',
  password: 'Password123!',
  displayName: 'John Doe', // optional
})

A verification code is sent to the user's email. To verify:

await AriariAuth.verifyEmail('a1b2c3d4...')

Sign in

const session = await AriariAuth.signIn({
  email: '[email protected]',
  password: 'Password123!',
})

console.log(session.idToken)      // JWT, expires in 1h
console.log(session.refreshToken) // opaque, for token renewal
console.log(session.uid)          // user unique ID
console.log(session.expiresIn)    // "3600"

Forgot / reset password

// sends a reset code to the user's email
await AriariAuth.forgotPassword('[email protected]')

// user receives the oobCode and submits a new password
await AriariAuth.resetPassword('a1b2c3d4...', 'NewPassword123!')

Phone / OTP

// send OTP
await AriariAuth.otp.send('+261340000000')

// verify OTP → returns a Session
const session = await AriariAuth.otp.verify('+261340000000', '123456')

Social Providers

All provider methods return a Session.

// Google
const session = await AriariAuth.provider.google(idToken)

// Facebook
const session = await AriariAuth.provider.facebook(accessToken)

// Apple
const session = await AriariAuth.provider.apple(identityToken)

// TikTok
const session = await AriariAuth.provider.tiktok(accessToken)

Session

The Session object

Every sign-in or OTP/provider call returns a Session:

| Field | Type | Description | |---|---|---| | idToken | string | JWT (HS256), expires in 1h — send as Authorization: Bearer to your own endpoints | | refreshToken | string | Opaque token for renewal — rotates on each refresh | | uid | string | User unique ID | | expiresIn | string | "3600" (seconds) |

Refresh

// from a Session instance
const renewed = await session.refresh()

// or from scratch with a stored refreshToken
const renewed = await AriariAuth.refresh(storedRefreshToken)

refreshToken rotates on every refresh — always store the latest one.

Sign out

// invalidates the session's refreshToken
await session.signOut()

// or pass the refreshToken directly
await AriariAuth.signOut(storedRefreshToken)

Decode idToken (server-side)

The idToken is signed with your app's tokenSecret (HS256). Verify it server-side with any JWT library:

import jwt from 'jsonwebtoken'

const payload = jwt.verify(idToken, tokenSecret) as {
  uid: string
  email?: string
  providers: string[]
  customClaims: Record<string, unknown>
}

Admin — User Management

Admin endpoints require an idToken from a signed-in admin user (passed as the first argument) and a projectId in the SDK config.

List users

const result = await AriariAuth.users.list(adminJwt)
// result.users  → ArAuthUserResponse[]
// result.total  → total user count
// result.page   → current page
// result.limit  → page size

// with pagination
const result = await AriariAuth.users.list(adminJwt, 2, 50)

Get a user

const user = await AriariAuth.users.get(adminJwt, uid)

Update a user

const updated = await AriariAuth.users.update(adminJwt, uid, {
  displayName: 'John Doe',
  photoURL: 'https://example.com/avatar.png',
  disabled: false,
  customClaims: { role: 'admin' },
})

Delete a user

await AriariAuth.users.delete(adminJwt, uid)

User response fields

| Field | Type | Description | |---|---|---| | uid | string | User unique ID | | email | string? | Email address | | emailVerified | boolean | Whether email is verified | | phone | string? | Phone number | | displayName | string? | Display name | | photoURL | string? | Avatar URL | | providers | string[] | Linked providers (email, google, phone, etc.) | | disabled | boolean | Whether the account is disabled | | customClaims | object | Custom metadata (e.g. { role: 'admin' }) | | createdAt | Date | Account creation date | | lastSignInAt | Date? | Last sign-in date |

Admin — App Config

Update your app's provider configuration programmatically:

await AriariAuth.app.update(adminJwt, {
  email: {
    enabled: true,
    smtpHost: 'smtp.gmail.com',
    smtpPort: 587,
    smtpUser: '[email protected]',
    smtpPass: '...',
    fromEmail: '[email protected]',
    fromName: 'MyApp',
  },
  phone: { enabled: true },
  google: { enabled: true, clientId: '...' },
  facebook: { enabled: true, appId: '...', appSecret: '...' },
  apple: { enabled: true, teamId: '...', keyId: '...', privateKey: '...', bundleId: '...' },
  tiktok: { enabled: true, clientKey: '...', clientSecret: '...' },
})

Multiple instances

Use name to manage separate AriariAuth instances (e.g. two apps in one codebase). AriariAuth.config() returns the instance directly.

const customerApp = AriariAuth.config({
  name: 'customer',
  appSecret: 'Ar-Auth_customer...',
})

const adminApp = AriariAuth.config({
  name: 'admin',
  appSecret: 'Ar-Auth_admin...',
  projectId: 'Ar-Prj_...',
})

const session = await customerApp.signIn({ email, password })
const users = await adminApp.users.list(adminJwt)

Retrieve a named instance later:

const customerApp = AriariAuth.get('customer')

Without name, the instance defaults to "main" and is used by all static methods (AriariAuth.signIn, AriariAuth.otp, AriariAuth.provider, etc.).

Config reference

| Option | Type | Required | Description | |---|---|---|---| | appSecret | string | Yes | Ar-Auth_... secret from your AriariAuth app | | projectId | string | No | Required for admin endpoints (user management, app config) | | baseUrl | string | No | Override API base URL (default: https://api.ariari.mg) | | name | string | No | Instance name (default: "main") |