Overview

Authenticating users is an essential element of a typical security model to confirm the identification of a user (or in some cases, a machine) that is trying to log on or access resources. Moxtra provides a Simplified SSO (Single Sign-On) approach, that accepts any unqiue string as a Unique ID (Example - email address, username, phone numbers, User ID, UID etc...) from your user management or identity system.

Authenticating Users

To authenticate an user using our platform API please make a simple HTTPS POST request to:

  • https://apisandbox.moxtra.com/oauth/token (for sandbox environment)
  • https://api.moxtra.com/oauth/token (for production environment)

POST /oauth/token
Host: https://apisandbox.moxtra.com
Content-Type: application/x-www-form-urlencoded

client_id=INSERT_CLIENT_ID&
client_secret=INSERT_CLIENT_SECRET&
grant_type=http://www.moxtra.com/auth_uniqueid&
uniqueid=INSERT_UNIQUE_USER_IDENTIFIER&
timestamp=TIMESTAMP&
firstname=INSERT_FIRST_NAME&
lastname=INSERT_LAST_NAME

On successful authentication and validating the request, Moxtra will return the access token as a JSON response. It'll look like::

{
    "access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw",
    "token_type": "bearer",
    "expires_in": 43199,
    "scope": "read write"
}

Request Parameters

Name Type Description
client_id String Required: The client ID you received from Moxtra when you registered.
client_secret String Required: The client secret you received from Moxtra when you registered.
grant_type String Required: This should always be set to 'http://www.moxtra.com/auth_uniqueid'.
uniqueid String Requried: unqiue string (Example - email address, username, phone numbers, User ID, UID etc...) from your user management or identity system.
timestamp String Required: UTC timestamp in millseconds. Current UTC time in milliseconds:
firstname String Optional: User's first name
lastname String Optional: User's last name
orgid String Optional: The Moxtra Organization (Org) ID. This parameter is only valid if you are creating separate Org for each of your customer account in Moxtra.
pictureurl String Optional: URL of user's avatar or profile picture
timezone String Optional: This user's timezone based on TZ string in the tz database. For example, America/Los_Angeles, Asia/Shanghai.
plancode String Optional: Plan code or package code assigned by Moxtra for the org. May not be applicable for most of the cases.
language String Optional: This user's language. Default is "en". The supported languages are:
  • da - Danish, dansk
  • de - German, Deutsch
  • en - English
  • es - Spanish, español
  • fi - Finnish, suomi
  • fr - French, français
  • id - Indonesian, Bahasa Indonesia
  • it - Italian, italiano
  • ja - Japanese, 日本語(にほんご)
  • ko - Korean, 한국어, 조선어
  • lt - Lithuanian, lietuvių kalba
  • nb - Norwegian Bokmål, Norsk bokmål
  • nl - Dutch, Nederlands, Vlaams
  • nn - Norwegian Nynorsk, Norsk nynorsk
  • no - Norwegian, Norsk
  • pt - Portugese, português
  • ru - Russian, Русский
  • sv - Swedish, svenska
  • th - Thai, ไทย
  • tr - Turkish, Türkçe
  • vi - Vietnamese, Tiếng Việt
  • zh - Chinese Simplified, 中文简体
  • zh-tw - Chinese Traditional, 中文繁體

Response Parameters

Name Description
access_token Token generated for the user to use with Moxtra API and SDKs.
token_type This always has the value of "bearer".
expires_in Access token expiration time (in seconds)

FAQs

What is orgid?

The orgid parameter refers to the Moxtra Organization (Org) ID. It is not a required parameter and should only be passed if you are creating separate organization in Moxtra for each of your customer accounts.

Do I need to create orgs?

Not always, depending on how your application handle the users you might create orgs in Moxtra. The flows here will help you to determine if you need to create orgs in Moxtra.

Use Case 1 - Users are not separated by customer accounts. You don't have to create a Moxtra Org.

UniqueID + Signature based SSO

Use Case 2 - Users are separated by customer accounts. You can choose to create Moxtra Org for this case.

UniqueID + Signature based SSO

How to create an organization in Moxtra?

To extend this feature into your integration flow with Moxtra APIs you will need to have a partner account in Moxtra, only then you will be able to create an organization in Moxtra. To learn more about our partnership program and creating orgs please contact us at partner@moxtra.com

Does Moxtra support other authentication methods?

Yes, Moxtra offers three different authentication methods.