General

What is an API?

“Application Programming Interface”. This allows a third party application to use a common set of services (such as Mobile Connect) via a defined interface. In the case of Mobile Connect the API can be called via an “Internet” connection so that Mobile Connect can be used in any application/ service that is ‘Internet Enabled’ e.g. a website or mobile phone application.

What is a REST API?

REST (Representational State Transfer) is a simple stateless architecture i.e. each operation is entirely defined by the information sent to and received from the service. When a web service uses this architecture, it is known as a REST API - Please visit http://www.restapitutorial.com/lessons/whatisrest.html

How do I incorporate Mobile Connect in my application?

Mobile Connect can be used from any application which is “Internet Enabled” – in practice the service will require the user to have a web browser that connects to the Mobile Connect service (actually a system component called the Identity Gateway) for the step when the user is logging in with their operator.

Developers are recommended to use the SDKs available from the developer portal – where available for their application platform. If developing an application and there is no SDK available the ‘REST’ versions of the Mobile Connect APIs can be used.

The developer portal details how the APIs work and should be used, and provide API references also. It is also a good idea to look at the Mobile Connect test applications to see how these use the APIs.

How should I associate a user’s Mobile Connect account with an existing account in my application?

Once a user has used Mobile Connect to authorize access to your application, the mobile network operator's Identity Gateway provides a Pseudo-anonymous Customer Reference (PCR) to the application. PCR is a unique reference to an individual user of Mobile Connect which reveals no personal information about the user. The PCR will be persistent for the same application and user (or MSISDN) logging in to the application and so this can be used to recognize either a first time user or a returning user.

In case there might already be a user account this can be paired by the application with the PCR value so that the user can use Mobile Connect to log in to the application in the future.

How do I recognise Mobile Connect is being used for a new user of my application?

Once a user has used Mobile Connect to authorize access to your application, the mobile network operator's Identity Gateway provides a Pseudo-anonymous Customer Reference (PCR) to the application. PCR is a unique reference to an individual user of Mobile Connect which reveals no personal information about the user. The PCR will be persistent for the same application and user (or MSISDN) logging in to the application and so this can be used to recognize either a first time user or a returning user.

In the case this is a new user of your application you will receive a new PCR and this shows you it’s a new user. From this you can create the relevant user record/ state/ settings in your application.

How do I obtain API keys?

Simply create a account on this developer portal and then can create one or more applications. Each application will get its own API keys. Once your application is ready to go live you can promote it to each of the mobile network operators that have a user base you want your application to access. This process is described in Request access to operator networks.

What data can I get from the Mobile Connect API?

The Mobile Connect service currently supports a simple authentication service – though there are plans to expand these capabilities in the future.
At the completion of the authentication process the mobile network operator's Identity Gateway provides a Pseudo-anonymous Customer Reference (PCR) – a unique reference to an individual user of Mobile Connect which reveals no personal information about the user. This is then used as the unique identifier for that user.

Some operators are already offering additional services and functionality such as “authorization” and “user attributes”. Please contact each mobile network operator directly for more information. Where possible, contact details are listed on the Mobile Connect Operators section of this portal.

Can Mobile Connect be used via Wi-Fi only device (i.e. a device with no SIM)

The Mobile Connect button can be used on any internet connected device. The Mobile Connect service itself requires that your users authentication device must be a SIM based device. This is because Mobile Connect account is linked to the SIM card and is provided and managed by the your users operator.

 


 

Technical

I see mention of a Redirect URI – what is this for?

This is part of the OpenID Connect authorization framework. This ensures authentication responses only go to your application/ service. This should point to a secure server hosted on your behalf – this should participate in the authorization process so that you can keep certain information from the APIs confidential (API secret, access token, PCR).

I am writing a mobile app – how should I define a Redirect URI?

Security is best when the Redirect URL points to a secure server that receives the authorization/ authentication response. You are advised to deploy a hosted service which participates in the authorization process and can keep certain details confidential to your application (API secret, access token, PCR). Although you may see code examples elsewhere which rely on ‘custom schemes’ e.g. calendar:// you are advised that your service should not use custom schemes (other than https) as these may not be supported across all Operator's.

How do I handle any service errors that are returned?

You will see details of various error responses within the API specifications. The Error description field in an authentication response is meant to detail a message for the user. Refer to the error code information that details what these mean and how these error codes should be handled.
Note that error text may vary between Operator's – it is intended to be displayed to the user who should be familiar with it.

What happens if an operator doesn't support Mobile Connect?

An error message will be returned to the application/ service to advise that Mobile Connect is not available for the user’s network – this will happen at the discovery stage. Your service should consider offering the user an alternate authentication method if available. Refer to documentation

What happens if a user accesses Mobile Connect but I've not signed an agreement with the operator?

The user will be presented with an error response at discovery or when the request is submitted for authorisation. Your service should consider offering the user an alternate authentication method if available. Refer to documentation

What happens if a user accesses Mobile Connect but they cannot use it for some reason?

The user will be presented with an error response when the request is submitted for authorisation. Your service should consider offering the user an alternate authentication method if available. Refer to documentation

What happens if the authentication request times out?

Your application will receive an error response indicating that the user has not authenticated. You should offer the user the ability to authenticate again with Mobile Connect or using an alternative authentication method.

The time out might have occurred for various reasons e.g. they took a phone call, were out of coverage for a while, or because the network is busy.

Does Mobile Connect work on all mobile devices?

There are certain device dependencies that may vary across mobile networks. In general operators are working on making Mobile Connect available to their whole customer bases. It should be possible to authenticate via all 3G/4G mobile devices but it may work differently across different versions of devices.

Are there any limitations on browser versions?

This may vary across mobile networks - Mobile Connect may not be usable on some networks if the user is accessing it from older, insecure browsers

How should I integrate Mobile Connect in my application?

Mobile Connect can be integrated into any ‘Internet Connected’ software environment. GSMA currently offers SDKs for Android, iOS and HTML5 integration and plans to introduce a range of server side SDKs for Java and PHP and others during 2016. See the SDK section in Documentation for the latest information.

In general, developers are encouraged to make most API calls from a server environment as this provides improved security and end user privacy. Some of the interactions in Mobile Connect must however be invoked within the user’s browser and therefore even if developers have built a typical client/server web application the GSMA SDKs will support certain API calls from the server side and other API calls from the client side. The recommendation is:

  • Discovery API calls are best made from a server environment
  • When the discovery user interface is displayed, this must be opened in the client browser (/webview)
  • The Mobile Connect authorization request must be opened in the client browser (/webview)
  • Mobile Connect token API (/userinfo API) should be made from the server environment
    If the application platform is not supported by a GSMA SDK the API calls can instead be made using HTTP based network API requests. Details on these network API requests are available in the API section of the Developer Portal.

Why does the sandbox only offers 2 pretend operators and doesn't work with real operators?

The sandbox is a emulator for the APIs and has been designed to be simple and global. It purpose is to to support the early stage of application development, which is why it offers only two emulated "operator's" APIs. Once an application has been tested against the sandbox APIs it is expected that the application will then require access to ‘real’ Mobile Connect services offered by the Mobile Network Operators. In line with this defined purpose, the sandbox is also only able to provide the simplest authorization method of SMS+URL.

Why does the sandbox only offers SMS authentication

SMS authentication is the authentication service that works universally across all devices and services. Other authenticators require integrations with specific operators (USSD + SIM App), operator linked downloads (SIM App) or integration with a specific smart app.

I don't get the authentication SMSs, what should I do?

If you are not able to receive an authentication SMS then please report the issue to the support team. You can also use the passthrough numbers that allow authentication with user interaction. You can find details on these here

 


 

SDKs

What is an SDK?

The abbreviation is for “software development kit” ... it is a kit of parts to support software /application developers in creating new applications for a particular environment or framework.

There are SDKs for software environments and frameworks e.g. Java, iOS, android. These SDKs are big and contain all the tools a developer needs to create a new applications in these particular environments.

There are also SDKs that support particular APIs e.g. Facebook Connect, Mobile Connect. These SDKs have a set of tools aimed specifically at supporting developers wanting to use the API services. These SDKs are a lot smaller than the full software environment SDKs but perform the same function i.e. they make it quicker and easier for the software developer to integrate the APIs in to their applications.

Why is there more than one SDK?

The GSMA Mobile Connect Platforms Team provide SDKs for the most popular software development environments that they believe will be using the Mobile Connect APIs.

Which software environments does the SDK support today?

Server side

  • Java SE/EE
  • PHP
  • .NET

Client side

  • Android
  • iOS
  • HTML5 (demo purposes only)

How are SDK tested?

Once a new version of an SDK is ready, is it sent to an independent software test house to be fully tested against the SDK requirement specification. Any bugs found are then fixed and it is re-tested. An SDK is not releases to developers until it has passed all the tests.

Who provides support for the SDKs?

The GSMA Mobile Connect Platforms Team provides on-boarding support to developers and in case there is an issue will normally get involved with problem identification. In case there is a problem with the SDK it will be referred to the supplier for rectification. The GSMA Mobile Connect Platforms Team also aims to help with related questions and maintaining the knowledge base for the SDKs.

Why do you only recommend the HTML5 SDK for prototyping and non-commercial use?

HTML5 is not a strongly secure environment and given the promise of Mobile Connect to keep user's personal data safe and private the HTML5 environment is not strong enough.

As such whilst the SDK has some use in developers understanding how to integrate Mobile Connect, but we would recommend other SDKs are used in commercial applications.

There are no plans to upgrade the HTML5 SDK to support Mobile Connect Release 2 Authorization and Identity services.

 


 

Security

Why do I need API credentials?

The API credentials identify your application/ service so that the user knows who/what is initiating Mobile Connect. These credentials are used by the operator to ensure they know which application/ service is originating the request.

Operator Identity Gateways will use this knowledge of the application/ service initiating the request to apply the relevant authenticator mechanism for a request, apply other operator policies e.g. API throttling limitations, and to guard against spoof authentication requests.

How do I keep credentials secure in a mobile app?

The general advice is that, as far as possible, API requests should be made exclusively from a server side environment – even if you have developed an Android or iOS application. You are encouraged to use mechanisms such as the iCloud keychain, and use methods such as code obfuscation to hide any API calls you make at a client environment.

Some API calls have to be placed from the client environment e.g. part of the discovery API request and part of the Mobile Connect authorization API call, but any time an API call involves a “secret” e.g. the second part of discovery or the Mobile Connect token API call you should make this from the server.

As a related note you should make sure that any of your code (client/ server) which is making API calls is using default SSL certificate checking. This will guard your applications/ users from potential man in the middle attacks if they are using an insecure network e.g. a WiFi hotspot.

If I have a native app without a server how can I secure the API credentials?

Certain OS platforms will provide secure storage environments e.g. the Apple iOS keychain.

You should certainly make sure not to store keys/ secrets to any form of removable storage.

“Hide” keys’ secrets in your code by breaking into ‘fragments’ which are spread in various places in your application and only combined when needed. And/ or use encryption and code obfuscation technologies particularly for Android applications which can be reverse compiled.

 


 

Commercial

Is there any restriction on the types of services I can use Mobile Connect for?

Mobile Connect is intended to be used for commercial services – however individual mobile operators may have specific policies in place over the types of services that they will allow Mobile Connect to be used with. You will need to consult the respective Terms & Conditions of each mobile operator to see what services are allowed or disallowed and may need to contact a team within the operator to discuss/ approve your application.

You should in general expect that Mobile Connect cannot be used for services which are considered illegal or immoral or otherwise forbidden in the user’s home country.

Am I charged for Mobile Connect API services?

Mobile Connect is provided by a global network of Mobile Operators and is delivered via a standardised technical interface. Each Operator has its own commercial proposition, pricing and commercial terms for Mobile Connect. You’ll need to agree to the Mobile Operator’s Terms and Conditions before you can access the service.

Some operators offer Mobile Connect Authenticate free of charge, subject to a fair usage policy, via a standard set of Terms and conditions on this developer.mobileconnect.io portal. Registered users can view and accept the Standard Terms and Conditions for these operators via the My Operators page.

For information about the commercial terms for operators not offering the Standard Terms and Conditions for Mobile Connect Authenticate, or other Mobile Connect products please contact the operators directly. Commercial contact details can be found in each Operator profile available at Operators page.

Is there a fair use/ reasonable use restriction?

Traffic levels for applications/ services will be monitored and may be subject to limitations to avoid problems for users, other applications or service platforms. Operator's may also have their own service limitations - please refer to the Operator’s specific terms & conditions.

How do I find out which operators are offering Mobile Connect?

A list of Operator's offering Mobile Connect with contact details can be found here.

How can I get in contact with the operators providing Mobile Connect?

A list of Operator's offering Mobile Connect with contact details can be found here.