Authorization API (OAuth 2.0)


Contents

Mxit Authorization and Authentication

Mxit's Authorization API ensures that applications are able to gain access to Mxit APIs and provide functionality, while respecting Mxit user preferences.

The API is accessible from both Mxit client applications (Mobi Portal and .NET) and other applications using the OAuth 2.0 framework.

Mxit's OAuth Authorization Server is accessed at https://auth.mxit.com, and we have published a list of all Mxit OAuth Scopes.

 

 

Getting Started

First, if you haven’t already, you need to register as a developer on the Mxit Developer Center.

You will then need to register your Application on the Mxit Developer Center. A Mxit Application is defined as any service making use of the Mxit APIs, such as a website, mobile app, Mobi Portal or Mxit service.

After your Application is registered, you will see the credentials (ClientId and ClientSecret) assigned to each application. Keep this information confidential. Should your ClientId or ClientSecret be compromised, there is an option on the Developer Center site to generate a new set of credentials for your Application.

 

Basics

When your Application wants to access a Mxit API, first it needs to send a request to the Mxit Authorization server. This request will contain the Application’s credentials (the ClientId and ClientSecret provided when you registered your Application) and the requested permissions (scopes) of the APIs you want to access.

If your request passes the Application authentication (ClientId & ClientSecret are correct) and Application authorization (your Application is allowed access to the requested API by Mxit), and (when required) the Mxit User grants you permission, you are returned an access token. Once you have the access token you can call the Mxit APIs directly using the access token as your Authorization credentials.

In cases where authentication or authorization isn't passed, you will receive an error response explaining what type of error occured. Be prepared to deal with situations where your applicaton credentials are correct, but the user does not choose to grant full permissions to your application. You may want to provide access to limited functionality in these cases, to avoid stopping these users from accessing your app completely.

Be sparing with the permissions you ask for. The higher the number of permissions you ask for, the greater the chance that a user might not decide to grant those permissions to your application.

The access token is valid for a certain period of time (currently 1 hour). Once the access token has expired, you will need to repeat this process to get a new access token. Alternatively, you may have also been returned a refresh token by the Mxit Authorization server - these have a longer lifetime (currently 24 hours), and can be used (until they expire) to request a new access token.

 

Authorization Flows

The Mxit Authorization Server supports a number of different OAuth2 flows that you can use within your applications.

The choice of which flow to use depends on the capabilities of your Application (web-site, mobile app, etc), and the requirements of the Mxit API you want to make use of.

 

Mxit Client Apps & Web Apps (User Permission Required)

This OAuth2 flow is used to request authorization from a user in an interactive way. As a HTTP redirection-based flow, the user must be online and can actively interact with the user-interface (web-browser or Mxit client). The initiator of the flow must be capable of receiving incoming requests (via HTTP redirection) from the Mxit Authorization server.

The Mxit Authorization server will check Application authentication (ClientId & ClientSecret correct) and Application authorization (your Application is allowed access to the requested API). The user will also be requiered to supply their credentials to the Authorization Server and authorize the access by the Application.

[Reference: http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1]

 

Authorization Code Request

The Application directs the user's client to make the following HTTP request to the Mxit Authorization server using TLS:

GET /authorize?response_type=code&client_id=s6BhdRkqt3        
&redirect_uri=https%3A%2F%2Fyour%2Ewebsite%2Ecom%2Fcallback
&scope=message&state=your_state HTTP/1.1
Host: auth.mxit.com

The parameters in the request are:

FieldRequiredFormatDescription
response_type Yes String Always "code"
client_id Yes String The ClientId assigned to your application.
redirect_uri Yes String The absolute URI on your server to which the client will be redirected to after the authorization completes.
scope Yes String The list of scopes which your application is requesting access to.
state No String State information you want passed back to your server after the authorization completes.

 

Authorization Code Response

A successful authorization request will perform a HTTP redirect the the redirect_uri specified in the request.

HTTP/1.1 302 Found     
Location: https://your.website.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=your_state

The returned Authorization Code can then be used to request an Access Token.

If an error occurs, or the user denies access, a redirect is also performed to the redirect_uri.

HTTP/1.1 302 Found     
Location: https://your.website.com/callback?error=access_denied&state=your_state

 

Token Request

The Application makes the following HTTP request to the Mxit Authorization server using TLS:

POST /token HTTP/1.1     
Host: auth.mxit.com
Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fyour%2Ewebsite%2Ecom%2Fcallback


The HTTP Authorization header is the Application (ClientId & ClientSecret) credentials. ie, Base64Encode( ClientId ":" ClientSecret )

The fields in the request are:

FieldRequiredFormatDescription
grant_type Yes String Always "authorization_code"
code Yes String The code returned in the Authorization Code response.
redirect_uri Yes String The redirect_uri from the Authorization Code request.

 

Token Response

If the request is valid and authorized, the Authorization server issues the token and returns the response:

HTTP/1.1 200 OK     
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"c71219af53f5409e9d1db61db8a08248",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"7f4b56bda11e4f7ba84c9e35c76b7aea",
"scope":"message"
}

The returned fields are:

FieldRequiredFormatDescription
access_token Yes String The Access Token to be used to access an API.
token_type Yes String Will always be "bearer".
expires_in Yes Integer The number of seconds for which the Access Token is valid.
refresh_token Yes String A Refresh Token which can be used to obtain a new Access Token.
scope Yes String The list of scopes for which the Access Token is valid.


Any Application (No User Permission Required)

This flow is used when only the credentials of the requester (ie, Application credentials) are available. The Mxit Authorization server can only check Application authentication (ClientId & ClientSecret correct) and Application authorization (your Application is allowed access to the requested API).

[Reference: http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4]

 

Request

The Application makes the following HTTP request to the Mxit Authorization server using TLS:

POST /token HTTP/1.1     
Host: auth.mxit.com
Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=message


The HTTP Authorization header is the Application (ClientId & ClientSecret) credentials. ie, Base64Encode( ClientId ":" ClientSecret )

The fields in the request are:

FieldRequiredFormatDescription
grant_type Yes String Always "client_credentials"
scope Yes String The list of scopes which you are requesting access to.

 

Response

If the request is valid and authorized, the Authorization server issues the token and returns the response:

HTTP/1.1 200 OK     
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"c71219af53f5409e9d1db61db8a08248",
"token_type":"bearer",
"expires_in":3600,
"scope":"message"
}

The returned fields are:

FieldRequiredFormatDescription
access_token Yes String The Access Token to be used to access an API.
token_type Yes String Will always be "bearer".
expires_in Yes Integer The number of seconds for which the Access Token is valid.
scope Yes String The list of scopes for which the Access Token is valid.

Note: For the Client Credentials flow, no refresh token is provided.

 

Javascript-only Web Apps (User Permission Required)

(We only recommend you use this in cases where you have a javascript-only web application. It is not the preferred method of authorization.)

This OAuth2 flow is used to request authorization from a user in an interactive way. As a HTTP redirection-based flow, the user must be online and can actively interact with the user-interface (web-browser or Mxit client). This flow is typically implemented in a browser using a scripting language such as JavaScript.

 [Reference: http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2]

 

Request

The Application directs the user's client to make the following HTTP request to the Mxit Authorization server using TLS:

GET /authorize?response_type=token&client_id=s6BhdRkqt3&redirect_uri=https%3A%2F%2Fyour%2Ewebsite%2Ecom%2Fcallback         
&scope=message&state=your_state HTTP/1.1 Host: auth.mxit.com

The parameters in the request are:

FieldRequiredFormatDescription
response_type Yes String Always "token"
client_id Yes String The ClientId assigned to your application.
redirect_uri Yes String The absolute URI to which the client will be redirected to after the authorization completes.
scope Yes String The list of scopes which your application is requesting access to.
state No String State information you want passed back to your server after the authorization completes.

 

Response

A successful authorization request will perform the following redirect the the redirect_uri specified in the request.

     HTTP/1.1 302 Found     Location: https://your.website.com/callback#access_token=c71219af53f5409e9d1db61db8a08248         
&token_type=bearer&expires_in=3600&scope=message&state=your_state

The fields in the HTTP redirect are:

FieldRequiredFormatDescription
access_token Yes String The Access Token to be used to access an API.
token_type Yes String Will always be "bearer".
expires_in Yes Integer The number of seconds for which the Access Token is valid.
scope Yes String The list of scopes for which the Access Token is valid.
state No String State information included with the request (if any).

If an error occurs, or the user denies authorization, a redirect is also performed to the redirect_uri.

HTTP/1.1 302 Found     Location: https://your.website.com/callback#error=access_denied&state=your_state

  

 

Refreshing an Access Token

If the Mxit Authorization server issued a refresh token to the Application, the Application can request a new access token using the refresh token until such time as the refresh token expires.

 

Request

The Application makes the following HTTP request to the Mxit Authorization server using TLS:

POST /token HTTP/1.1     
Host: auth.mxit.com
Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=7f4b56bda11e4f7ba84c9e35c76b7aea

The HTTP Authorization header is the Application (ClientId & ClientSecret) credentials. ie, Base64Encode( ClientId ":" ClientSecret )

The fields in the request are:

FieldRequiredFormatDescription
grant_type Yes String Always "refresh_token"
refresh_token Yes String The Refresh Token obtained previously.

 

Response

If the request is valid and authorized, the Authorization server issues the access token and returns the response:

HTTP/1.1 200 OK     
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"5ece35036e814d93952b4d12c52d07d9",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"7f4b56bda11e4f7ba84c9e35c76b7aea",
"scope":"profile"
}

The returned fields are:

FieldRequiredFormatDescription
access_token Yes String The Access Token to be used to access an API.
token_type Yes String Will always be "bearer".
expires_in Yes Integer The number of seconds for which the Access Token is valid.
refresh_token Yes String A Refresh Token which can be used to obtain a new Access Token.
scope Yes String The list of scopes for which the Access Token and Refresh Token is valid.

Note: The refresh token remains the same as in the request.

 


Token Revocation

Access and Refresh Tokens can be revoked by your application. For security reasons your application might want to revoke tokens allocated when the user logs-out, their session expires, etc.

Request

The Application makes the following HTTP request to the Mxit Authorization server using TLS:

POST /revoke HTTP/1.1     
Host: auth.mxit.com
Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type: application/x-www-form-urlencoded
token=c71219af53f5409e9d1db61db8a08248


The HTTP Authorization header is the Application (ClientId & ClientSecret) credentials. ie, Base64Encode( ClientId ":" ClientSecret )

The fields in the request are:

FieldRequiredFormatDescription
token Yes String The token to be revoked.

 

Response

If the request is valid and authorized, the Authorization server will reply with a 200 HTTP Status code.

A 401 status code indicates that the client application failed authentication.

A 403 status code indicates that the client is not authorized to revoke the specified token.

A 400 status code indicates that the token is invalid.


Accessing the Mxit APIs

Now that an access token has been granted by the Mxit Authorization server, the Application can make calls to the API using this token. The access token is passed via the HTTP Authorization header in every request to the API.

For example,

GET /user/@me/email HTTP/1.1     
Host: profile.api.mxit.com
Authorization: Bearer 5ece35036e814d93952b4d12c52d07d9

The API server will validate that the access token is valid, has not expired, and ensure that its scope covers the requested resources.

If the token is not valid for any of the above, an HTTP error will be returned by the API Server.

For example,

HTTP/1.1 401 Unauthorized   
WWW-Authenticate: Bearer realm="Mxit Authorization",
error="invalid_token",
error_description="The access token expired"

The following errors are defined in the OAuth2 specification [2]"

invalid_request 
The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The resource server SHOULD respond with the HTTP 400 (Bad Request) status code.
invalid_token 
The access token provided is expired, revoked, malformed, or invalid for other reasons. The resource SHOULD respond with the HTTP 401 (Unauthorized) status code. The client MAY request a new access token and retry the protected resource request.
insufficient_scope 
The request requires higher privileges than provided by the access token. The resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY include the "scope" attribute with the scope necessary to access the protected resource.

 

 

Terminology

Access Token
A case-sensitive text string (eg, "0cd34b0f2b764bdd957318c7dfe30a87") which is used to access a Mxit API.
Refresh Token
A case-sensitive text string which can be used to request a new Access Token when your current Access Token has expired.
Scope (aka. Permissions)
A list of space-delimited, case-sensitive strings which specify a which APIs you're requesting access to, or the list of APIs the Access Token grants you access to. These string will be defined by the various Mxit APIs (eg, "profile" for user information, or "message" for Messaging). The "/" character will be used to denote sub-scopes (eg, "profile/public" as Public profile information of the User).

References

OAuth 2.0 Authorization Framework

OAuth 2.0 Authorization Framework: Bearer Tokens

OAuth Token Revocation