Using the library

Initialize Client

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

You can also initialize the client with an accessToken, refreshToken and idToken

...

const headers = {
    idToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    accessToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    refreshToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
}

const client = Auth(url, headers);

Sign In

signInWithEmailAndPassword

You can use signInWithEmailAndPassword to let your users authenticate with OA's authentication service using their email addresses and passwords.

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

const username = 'testuser@oamarkets.com';
const password = 'MySuperSecretPassword123!';

const { data, error } = await client.signInWithEmailAndPassword({
  username,
  password,
});

The signInWithEmailAndPassword promise returns a payload of type:

{
  data: {
    accessToken: string;
    idToken: string;
    refreshToken: string;
  },
  error: undefined;
}

signInWithAuthCode

You can use signInWithAuthCode to get an access, refresh and Id token after a social sign on.

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

const code = 'ABCDEFGH';

const { data, error } = await client.signInWithAuthCode({
  code,
  redirectUri: 'https://oamarkets.com',
  source: 'settlement',
});

The signInWithAuthCode promise returns a payload of type:

{
  data: {
    accessToken: string;
    idToken: string;
    refreshToken: string;
  },
  error: undefined;
}

renewToken

This is useful for providing an uninterrupted user experience when an access token expires while the user is active. It returns a CognitoUserSession object which contains JWT accessToken, idToken, and refreshToken.

This method will automatically refresh the accessToken and idToken if tokens are expired and a valid refreshToken presented.

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.renewToken({
  refreshToken: 'sample-refresh-token',
});

The renewToken promise returns a payload of type:

{
  data: {
    accessToken: string;
    idToken: string;
    refreshToken: string;
  },
  error: undefined;
}

Sign up

createUserWithEmailAndPassword

To create a new user account with a password, complete the following steps in your app's sign-up page:

1. When a new user signs up using your app's sign-up form, complete any new account validation steps required, such as verifying that the new account's password meets the set complexity requirements. Make sure the country matches the correct country ISO code. View getCountries for more info on getting the list of approved countries.
2. Create a new account by passing the new user's email address and password to createUserWithEmailAndPassword

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL
// Your OA tokens ( accessToken, refreshToken, idToken )

import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.createUserWithEmailAndPassword({
  email: 'testuser@oamarkets.com',
  password: 'MySuperSecretPassword123!',
  confirmPassword: 'MySuperSecretPassword123!',
  firstName: 'John',
  lastName: 'Doe',
  source: 'settlement',
  phoneNumber: '+233551234567',
  country: 'GH',
});

The createUserWithEmailAndPassword promise returns a payload of type:

{
  data: {
    user: {
      username: string;
    };
    userConfirmed: false;
    userSub: string;
    codeDeliveryDetails: {
      AttributeName: string;
      DeliveryMedium: string;
      Destination: string;
    };
  },
  error: undefined
}

An email is sent to the provided email address for account confirmation.

getCountries

This returns all the supported countries and its meta data

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL
// Your OA tokens ( accessToken, refreshToken, idToken )

import Auth from 'oa-auth';
const client = Auth({ url, headers });

const { data, error } = await client.getCountries({ appId: string });

The getCountries promise returns a payload of type:

{
  data: {
    name: string;
    callCode: string;
    isoCode: string;
    disabled: boolean;
    flag: string | null;
    createdAt: string;
    updatedAt: string;
  }
  [];
  error: undefined;
}

Account Recovery

changePassword

You can set a user's password with the changePassword method. For example:

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.changePassword({
  previousPassword: 'myPreviousPassword';
  proposedPassword: 'myNewPassword';
  confirmProposedPassword: 'myNewPassword';
});

The changePassword promise returns a payload of type:

{
  data: {
    message: string;
  },
  error: undefined;
}

You can set a user's password with the updatePassword method. For example:

sendPasswordResetEmail

This sends a password reset email to a user with the sendPasswordResetEmail method. For example:

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth({ url, headers });

const { data, error } = await client.sendPasswordResetEmail({
  username: 'testuser@oamarkets.com';
});

The sendPasswordResetEmail promise returns a payload of type:

{
  data: {
    "CodeDeliveryDetails": {
      "DeliveryMedium": string;
      "AttributeName": string;
      "Destination": string;
    }
  },
  error: undefined;
}

confirmForgotPasswordCode

Takes the confirmation code after calling sendPasswordResetEmail and resets the specified user password to a new password

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth({ url, headers });

const { data, error } = await client.sendPasswordResetEmail({
  username: 'abc@example.com',
  confirmationCode: '12345',
  proposedPassword: 'Ab!*45@#sgh',
  confirmProposedPassword: 'Ab!*45@#sgh',
});

The confirmForgotPasswordCode promise returns a payload of type:

{
  data: {
    messasge: string;
  },
  error: undefined;
}

Manage Users

getCurrentUser

The getCurrentUser property returns the user's profile information of the currently signed-in user.

This method requires a valid accessToken

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL
import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.getCurrentUser();

The getCurrentUser promise returns a payload of type:

{
  data: {
    "UserAttributes": [
      {
        "Name": string;
        "Value": string;
      }
    ],
   "Username": string;
  },
  error: undefined;
}

updateCurrentUser

You can update user attributes with updateCurrentUser

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL

import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.updateCurrentUser({
  tin: string;
  address: string;
  city: string;
  country: string;
  birthdate: string;
  alternateEmail: string;
  provinceStateRegion: string;
});

The updateCurrentUser promise returns a payload of type:

{
  data: {
    message: string;
  }
  error: undefined;
}

signOut

By using signOut, you sign out users from all devices. It also invalidates all refresh tokens issued to a user. The user's current access and Id tokens remain valid until their expiry. Access and Id tokens expire one hour after they are issued.

This method requires a valid accessToken

const url = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your OA auth URL
const headers = {
  accessToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
};

import Auth from 'oa-auth';
const client = Auth(url);

const { data, error } = await client.signOut();

The signOut promise returns a payload of type:

{
  data: {
    message: string;
  }
  error: undefined;
}