OAuth 2 Authentication

Moxtra's API use the OAuth 2.0 protocol, a popular open standard used by most APIs for authenticating and authorizing users. This document outlines the OAuth 2.0 authorization scenarios supported by Moxtra.

If you are building an application that only has client side components then you should use the Client-Side (Implicit) Flow model.

If your application has server side components then you should use the Server-Side (Explicit) Flow.

In most cases you will be using one of these two authentication models.

Endpoint

Moxtra OAuth request endpoint (for production): https://api.moxtra.com/
Moxtra OAuth request endpoint (for sandbox): https://apisandbox.moxtra.com/

Register

All applications using OAuth2 authentication with Moxtra must be registered through our app registration console. A registered application is assigned with an unique Client ID and Client Secret.

Client-Side (Implicit) Flow

You will be using this flow when building an application that does not have a server component.

1. Begin authorization & request access token

Redirect user to Moxtra for authorization

https://apisandbox.moxtra.com/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token
Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when you registered.
response_type String For the implicit flow, this should always be set to 'token'
redirect_uri String Optional: Determines where the response is sent. The value of this parameter must exactly match to the value you specified when registering your app.

2. Get access token

If the user authorize the request successfully with Moxtra, Moxtra will redirect the user back to your application following the URI specified by 'redirect_uri'. The parameters are passed back in the URI's hash, not the query string. It'll look like:

http://redirect_uri#access_token=ACCESS-TOKEN&token_type=bearer&expires_in=EXPIRATION-TIME
Response Parameters
Name Description
access_token Access token for use in Moxtra API calls.
token_type This always has the value of bearer.
expires_in Expiration time (in seconds)

3. Make API Calls

After your application extracts the access token from the URI hash, you can use the token to make requets to a Moxtra API. To do this, include the access token in a request to the API. Please note that the implicit flow's access_token is short lived and cannot be configured. When the token expires, the user will have to login and authorize again.

Server-Side (Explicit) Flow

The server-side flow works by sending your user to Moxtra for authorization with the following process:

1. Begin authorization & request authorization code

Redirect user to Moxtra for authorization

https://apisandbox.moxtra.com/oauth/authorize?client_id=CLIENT-ID&response_type=code
Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when you registered.
response_type String For the explicit flow, this should always be set to 'code'
redirect_uri String Optional: Determines where the response is sent. The value of this parameter must exactly match to the value you specified when registering your app.

2. Get authorization code & request access token

If the user authorize the request successfully with Moxtra, Moxtra will redirect to the 'redirect_uri' with an authorization code. It'll look like:

http://redirect_uri?code=CODE
Response Parameters
Name Description
code Temporary code which will be used to get the access token.

Exchange the authorization code for an access token and a refresh token through a HTTPS POST request as shown in the below:

POST https://apisandbox.moxtra.com/oauth/token
    client_id=CLIENT-ID&
    client_secret=CLIENT-SECRET&
    grant_type=authorization_code&
    code=CODE
Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when you registered.
client_secret String The client secret you received from Moxtra when you registered.
grant_type String This should always be set to 'authorization_code'
code String The exact authorization code you received from the previous step
redirect_uri String Optional: If redirect_uri is specified in /oauth/authorize request, the same redirect_uri becomes required in /oauth/token.

3. Get access token

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

{
    "access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw",
    "token_type": "bearer",
    "refresh_token": "VcgxMQAAATp7M06eACeNAFVpYWR1RVNXc2J6Rm9LOVRPbGRDNnpGAAAAAw",
    "expires_in": 43199,
    "scope": "read write"
}
Response Parameters
Name Description
access_token Access token for use in Moxtra API calls.
token_type This always has the value of bearer.
refresh_token Refresh token may be used to refresh the access token when it expires (good for 30 days)
expires_in Expiration time (in seconds)

4. Make API Calls

After your application extracts the access token from the above-mentioned step, you can use the token to make requets to a Moxtra API. When the token expires, you can use refresh token to refresh the access token and if the refresh token is expired user will have to login and authorize again.

Refresh token

Refresh token allows your app to persist granted access without forcing the user to reauthorize your app. For each request, in addition to a new access_token getting generated, a new refresh_token also gets returned. The new refresh_token has a lifespan of 30 days from the time it's generated. You can refresh token through a HTTPS POST request as shown below:

curl \-F 'client_id=CLIENT-ID' \
-F 'client_secret=CLIENT-SECRET' \
-F 'grant_type=refresh_token' \
-F 'refresh_token=REFRESH-TOKEN' \https://apisandbox.moxtra.com/oauth/token
Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when you registered.
client_secret String The client secret you received from Moxtra when you registered.
grant_type String This should always be set to 'refresh_token'.
refresh_token String The exact refresh token you received from the original request with the access token.

On successful request, sample respone as follows:

{
    "access_token": "vI0wMgAAAVHLaPAcACeNAFV0a2ozWUM1QnhSSENDYXE5d2lkUDY3IAAAAAdU",
    "token_type": "bearer",
    "refresh_token": "YHcxMgAAAVHLaPAcACeNAFV0a2ozWUM1QnhSSENDYXE5d2lkUDY3IAAAAAd",
    "expires_in": 43199,
    "scope": "read write"
}

Revoke Access Token

Access token can be revoked while still in effect through a HTTPS POST request as shown below:

curl \-F 'access_token=ACCESS-TOKEN' \https://apisandbox.moxtra.com/oauth/revoke
Request Parameters
Name Type Description
access_token String A valid access token.

SAML Bearer

The OAuth 2.0 SAML bearer assertion flow defines how a SAML assertion can be used to request an OAuth access token when a client wishes to utilize a previous authorization, more details can be found at http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer.

1. Configuration

The configuration is same as documented in our SAML Single Sign On documentation except the following.

  • SP entityID for Audience - http://api.moxtra.com
  • SP Access Consumer Service endpoint for Recipient - "https://api.moxtra.com/oauth/token"

2. Create SAML Bearer Assertion

Obtain the assertion from the Identity Provider, the assertion must be signed according to the XML Signature specification , using RSA and either SHA-1 or SHA-256.

Here is a sample assertion

<?xml version="1.0" encoding="UTF-8"?>
    <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="maegkddcbcljpaddamchldbfgmifaabmchfiehoh" IssueInstant="2013-06-05T01:22:41Z" Version="2.0">
        <Issuer>sampleidptest</Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
            <ds:Reference URI="#maegkddcbcljpaddamchldbfgmifaabmchfiehoh">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <ds:DigestValue>WP4hmTbZ4rNf9mLdXR6mijCTqns=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
hEnxtDX+mSyljDvkWPfy//5XTuygRLUJ3hIzhVfv/c7vm/WvLVpftSc3LSeVIII9bHAM2hwoT/5T9WYOoFFGl6+2/fiQXS+L1kPx3enX6SQOZJuZh6NZrwj6O0F1fts8ZEmRs1zAfhBxrLjOmIjEWhC+A0iuHJeSs1sE8teK04Zv4eu4Ir/xZSrnmL4cH03EZo9NJdKMWmTKoY1Fp+i7fjHEa6MiPcUSznuDQilMDeW3ECbqqwEgZwyyvSscPZgr/s5ZUsOYeFwD3MhtpAzM+DF/a5k4Q+wA5POIyGYJZ4aCXw4u77S7RATCbNgsZaOPLLgyrwf7SIT4DTGZfFrSZg==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509SubjectName>
CN=*.moxtra.com,OU=Terms of use at www.verisign.com/rpa (c)05,O=Moxtra\, Inc.,L=Cupertino,ST=California,C=US
                </ds:X509SubjectName>
                <ds:X509Certificate>
MIIFWDCCBECgAwIBAgIQckTX7Th3KRVw+5W/TTM+EDANBgkqhkiG9w0BAQUFADCBtTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykxMDEvMC0GA1UEAxMmVmVyaVNpZ24gQ2xhc3MgMyBTZWN1cmUgU2VydmVyIENBIC0gRzMwHhcNMTMwMTI5MDAwMDAwWhcNMTcwMTI5MjM1OTU5WjCBmTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExEjAQBgNVBAcUCUN1cGVydGlubzEVMBMGA1UEChQMTW94dHJhLCBJbmMuMTMwMQYDVQQLFCpUZXJtcyBvZiB1c2UgYXQgd3d3LnZlcmlzaWduLmNvbS9ycGEgKGMpMDUxFTATBgNVBAMUDCoubW94dHJhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANSILv9Jysk5zCGBAdArLLOGtmRjWaLOixLUdQORnHF0VqwlVr6UYmTTQLsnbbS7uFp32Xm/fd18k6Wlydyl64XkqHYlbNcMErM6prlN5tN0MvTvOygOCTlLdmOqmf7KqASGAtZ32DkDIHlmArTTRSmhfWk/PgK2RjWGDgz1pXrpGCIZXJbgtA6a2E4mJr8g0+3h7HLA/VKJpkrWKhgt9aJewzf+p2Ab0EDfTrdJ9LhSXUMkgR+2CfIkVHEsksPiB+TlTTgnlJ9+d6t6iCSWXYBGCZB33wtWgtCHkDsq5GtEPoiUpbagO6LtYoxltjhdfLiZdwI7aqRHHn8UMDG3XT0CAwEAAaOCAXwwggF4MBcGA1UdEQQQMA6CDCoubW94dHJhLmNvbTAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIFoDBFBgNVHR8EPjA8MDqgOKA2hjRodHRwOi8vU1ZSU2VjdXJlLUczLWNybC52ZXJpc2lnbi5jb20vU1ZSU2VjdXJlRzMuY3JsMEMGA1UdIAQ8MDowOAYKYIZIAYb4RQEHNjAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy52ZXJpc2lnbi5jb20vY3BzMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAfBgNVHSMEGDAWgBQNRFwWU0TBgn4dIKsl9AFj2L55pTB2BggrBgEFBQcBAQRqMGgwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNvbTBABggrBgEFBQcwAoY0aHR0cDovL1NWUlNlY3VyZS1HMy1haWEudmVyaXNpZ24uY29tL1NWUlNlY3VyZUczLmNlcjANBgkqhkiG9w0BAQUFAAOCAQEAkKwB3bMdqJbKUDVOI9VgH8adRqw50djPyxme7/XL+v507txaQnSFa9KMUtzn7lvB8E4C7yU51SFBHJyMfygEig2yLcqsjAor4z4i9lr4KcOA0tV7iT3Q67JPsVPENqEXk+LngZZhHSdvrss0+frGUVn0shFrZzRSXWzaz/E8+xiDBQ3g3kuo2p9bLjL8HmhZQSDwCbL74UsuJmSaw57XODzdcGg+Fm7V6gx3pXGcdoU/a8rJz7Sea0TSHc+Q7SgnFsvulwGZktZN21oNHLJ7k9RvLfx3AeSp7S1J4lvdDPnAoJfaWrIIjve/pUaCcuofAYPIjUN+E3jR2yIxpmHcTw==
                </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
        </ds:Signature>
        <Subject>
            <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
                test@xyz.com
            </NameID>
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <SubjectConfirmationData NotOnOrAfter="2013-06-05T01:32:41Z" Recipient="https://api.moxtra.com/oauth/token" />
            </SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="2013-06-05T01:17:41Z" NotOnOrAfter="2013-06-05T01:32:41Z">
            <AudienceRestriction>
                <Audience>http://api.moxtra.com</Audience>
            </AudienceRestriction>
        </Conditions>
        <AuthnStatement AuthnInstant="2013-06-05T01:22:41Z">
            <AuthnContext>
                <AuthnContextClassRef>
                    urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
                </AuthnContextClassRef>
            </AuthnContext>
        </AuthnStatement>
</Assertion>

3. Request and get access token

To get the access token using the SAML bearer assertion make a HTTPS POST request to https://api.moxtra.com/oauth/token as shown in the below sample request.

POST https://api.moxtra.com/oauth/token
    client_id=CLIENT-ID&
    client_secret=CLIENT-SECRET&
    grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&
    idpid=IDP-ID&
    orgid=ORD-ID&
    assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv...
Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when you registered.
client_secret String The client secret you received from Moxtra when you registered.
grant_type String This should always be set to 'urn:ietf:params:oauth:grant-type:saml2-bearer'.
idpid String Issuer Entity ID.
assertion String SAML bearer assertion as created in the previous step, encoded using base64.
orgid String Optional: Organization ID received from Moxtra; Required for Org based SSO.
partnerid String Optional: Partner ID received from Moxtra; Required for Partner based SSO.

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

{
    "access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw",
    "token_type": "bearer",
    "expires_in": 43199,
    "scope": "read write"
}
Response Parameters
Name Description
access_token Access token for use in Moxtra API calls.
token_type This always has the value of bearer.
expires_in Expiration time (in seconds)