The Discovery API

Overview

The Discovery Service provides an application with details of the the end-users operator. Once these details have been obtained then the application will be able to make Mobile Connect calls to the operators endpoints.

The Service has various methods of identifying the operator. Where possible, this is done in the background (without user interaction), but in some situations it is necessary to ask an end-user to provide additional details. In this case the Discovery Service will present an "Operator Selection User Interface" which prompts the end user to enter their MSISDN or select their operator.

This document explains the different requests that are available to applications as well as specifying the details of the API.

API Reference

Request

GET {Provider}/v2/discovery/?query_parameters

POST {Provider}/v2/discovery/

 

Header parameters

Parameter name Value Description
Mandatory parameters
Authorization string HTTP Basic authorization to access the API. Base64 encoded string of your <client_id>:<client_secret>

Optional parameters
Accept string Indicates the content type required for the response. text/html can be used on the request with OperatorSelection request to get an HTML response. For all other requests, always default to application/json

Accepted Values:

  • application/json
  • text/html

 

Query parameters

Parameter name Value Method Description
Mandatory parameters
Redirect_URL string POST
GET		 The Redirect URL that you set when you create your application. Determines where Discovery Service sends responses to your OperatorSelection request.
Optional parameters
Identified-MCC string POST
GET		 The 3 Digit Numeric Mobile Country Code of the device SIM Card - normally obtained via a native os application.
Identified-MNC string POST
GET		 The 2 or 3 Digit Numeric Mobile Network Code of the device SIM Card - normally obtained via a native os application.
Selected-MCC string POST
GET		 The 3 Digit Numeric Mobile Country Code of the response from the Operator Selection WebApp.
Selected-MNC string POST
GET		 The 2 or 3 Digit Numeric Mobile Network Code of the response from the Operator Selection WebApp.
Using-Mobile-Data boolean POST
GET		 Set to true if your application is able to determine that the user is accessing the service via mobile data. This tells Discovery Service to attempt to discover using information provided by the mobile network.

Default: true
MSISDN string POST The mobile number, in E.164 number format, of your user.
X-Source-IP IP address POST
GET		 The IP address of the users device. If the device is making a Discovery request directly then this is not needed as it is picked up automatically. If the application is client/server based then the server can use the this to pass in the IP address of the client and to tell Discovery to ignore the request IP address. The IP address is used by Discovery to try and detect the users operator.
X-Redirect string POST
GET		 Indicates if the error responses in the discovery UI flow should be returned as JSON errors rather than handled within the discovery UI. This allows the requesting application to manage the user error flow.

 

Discovery Requests

The following is a list of the possible Discovery requests

 

User selected MCC/MNC with GET

GET /v2/discovery{?Selected-MCC,Selected-MNC}

When the country and operator have been selected by the user via the Discovery UI, this is passed to the API Exchange via the Discovery API and the MNOs endpoints are returned.

URI Parameters

Parameter Type Required Example
Selected-MCC string Yes 902
Selected-MNC string Yes 02
Redirect_URL string Yes https://localhost/

 

Request

The following request use the Sandbox

GET https://discovery.sandbox.mobileconnect.io/v2/discovery?Selected-MCC=902&Selected-MNC=02&Redirect_URL=https://localhost/

 

Headers

Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

 

Examples

The following Sandbox examples can be used to get the response described below.

cURL

Copy and paste the curl command below into your command line interface

curl -v "https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https://localhost/&Selected-MCC=902&Selected-MNC=02" -basic -u "a75e3360-c365-4126-a57b-5748ca59e899:45f2a32c-7d7d-40e2-9601-22f2ddab62de"

 

Postman

Copy the text below and import into Postman using Import → Paste Raw Text

curl -X GET \
  'https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https%3A%2F%2Flocalhost%2F&Selected-MCC=902&Selected-MNC=02' \
  -H 'authorization: Basic YTc1ZTMzNjAtYzM2NS00MTI2LWE1N2ItNTc0OGNhNTllODk5OjQ1ZjJhMzJjLTdkN2QtNDBlMi05NjAxLTIyZjJkZGFiNjJkZQ==' \
  -H 'cache-control: no-cache'

 

Response 200 OK

  • Two cookies are set (this is default for the discovery response, unless Set-Cookies parameter is set to false in the request)

Headers

Content-Type: application/json

Cookies

Name Value Domain Path Expires HTTP Secure
Recent-Selected-Operator 5885cafbbba12f25546a9cdf discovery.sandbox.mobileconnect.io /v2 Never true false
Recent-Selected-Operator-Expiry 2017-03-08T11:24:33.921586 discovery.sandbox.mobileconnect.io /v2 Never true false

Body

{
  "subscriber_id": null,
  "ttl": 1488452073,
  "response": {
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI=",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "currency": "USD",
    "client_name": "TestApp",
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI="
  }
}

Schema

{
  "": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ttl": {
      "type": "string",
      "description": "A unix timestamp indicating the "time to live" of the response object. A timestamp in the future indicates that this response may be cached to improve performance. The `ttl` value does not have to be in the future and if it's not, the response object should not be cached.\n"
    },
    "subscriber_id": {
      "type": "string",
      "description": "    MSISDN value encoded with operator RSA certificate that can be passed along as "login_hint" parameter of the Mobile Connect API. This response value is only available when the request contains an MSISDN on the `MSISDN` parameter. The `subscriber_id` is opaque to the service provider's application in that it cannot be decypted by the application - it can only be used to pass to the mobile connect API in order to streamline the users login (potentially saving them entering an MSISDN for a second time).\n"
    },
    "response": {
      "type": "object",
      "properties": {
        "client_id": {
          "type": "string",
          "description": "00a9-4421-90d0-82cf76eba7e0 (string, required)\n\nclient_id part of your credential to be used by OIDC requests. It's important to note that this will likely not be the same as the client_id used for the discovery request and it's not safe to assume the client_id will be the same (or a variation of) the discovery request key.\n"
        },
        "client_secret": {
          "type": "string",
          "description": "4e73-4bc0-91e7-16b40cf75c67 (string, required)\n\nclient_secret part of your credential to be used by OIDC requests. Much like the `client_id`, this may be different to the discovery request credential.\n"
        },
        "serving_operator": {
          "type": "string",
          "description": "The name of the users mobile network operator (MNO)."
        },
        "country": {
          "type": "string",
          "description": "The country name in which this network operates."
        },
        "currency": {
          "type": "string",
          "description": "The currency of the serving operator."
        },
        "client_name": {
          "type": "string",
          "description": "A short app name which can be used for the `client_name` parameter on mobile connect auth requests."
        },
        "apis": {
          "type": "object",
          "properties": {
            "operatorid": {
              "type": "object",
              "properties": {
                "link": {
                  "type": "array",
                  "description": "The links describe the available endpoints for the operator. These endpoints can be used to perform mobile connect operations for the discovered MSISDN or MNC/MCC pair.\n"
                }
              },
              "required": [
                "link"
              ]
            }
          },
          "required": [
            "operatorid"
          ],
          "description": "An object describing the available interfaces for this operator which currently includes mobile connect auth related endpoints, as well as premiuminfo endpoints."
        }
      },
      "required": [
        "country",
        "currency",
        "client_name",
        "apis"
      ],
      "description": "The response object contains details of the API exchange endpoints for the MSISDN or MCC/MNC pair passed into the discovery request which are valid for the service providers application."
    }
  },
  "required": [
    "ttl",
    "response"
  ]
}

 

Response 400 Bad Request

Description

The MNC is not provided.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid_Request",
  "description": "The Mnc value is not specified in this discovery request"
}

 

Response 400 Bad Request

Description

The MCC is not provided.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid_Request",
  "description": "The Mcc value is not specified in this discovery request"
}

 

Response 400 Bad Request

Description

Redirect_URL is not provided.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid_Request",
  "description": "Redirect_URL missing"
}

 

Response 401 Unauthorized

Description

The request credentials are not valid.

Headers

Content-Type: application/json

Body

{
  "error": "Unauthorized_Access",
  "description": "Please provide correct credentials"
}

 

Response 404 Not Found

Description

The MCC/MNC pairing does not match an operator

Headers

Content-Type: application/json

Body

{
  "error": "Not_Found_Entity",
  "description": "There is no organization with the specified mcc/mnc pair"
}

 

User selected MCC/MNC with POST

POST /v2/discovery

When the country and operator have been selected by the user via the Discovery UI, this is passed to the API Exchange via the Discovery API and the MNOs endpoints are returned.

Example URI

POST https://discovery.sandbox.mobileconnect.io/v2/discovery

Request

Headers

Content-Type: application/x-www-form-urlencoded'
Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

Body

'Redirect_URL=http%3A%2F%2Flocalhost%2F&Selected-MNC=02&Selected-MCC=902'

Schema

{
  "type": "object",
  "properties": {
    "Redirect_URL": {
      "type": "string",
      "description": "The Redirect URL that you set when you create your Application that determines where Discovery Service sends responses to your OperatorSelection request.\n"
    },
    "Identified-MCC": {
      "type": "string",
      "description": "3 Digit Numeric "Mobile Country Code" of the device SIM Card obtained via Native (e.g. Android) application. `Identified-MCC` and `Identified-MNC` must be used together and are mutually exclusive witht the `Selected-*` parameters.\n"
    },
    "Identified-MNC": {
      "type": "string",
      "description": "2 Digit Numeric "Mobile Network Code" of the device SIM Card obtained via Native application.\n"
    },
    "Selected-MCC": {
      "type": "string",
      "description": "3 Digit Numeric "Mobile Country Code" of the response from the OperatorSelection WebApp. `Selected-MCC` and `Selected-MNC` must be used together and are mutually exclusive witht the `Identified-*` parameters.\n"
    },
    "Selected-MNC": {
      "type": "string",
      "description": "2 Digit Numeric "Mobile Network Code" of the response from the OperatorSelection WebApp.\n"
    },
    "Using-Mobile-Data": {
      "type": "boolean",
      "description": "Set to "true" if your application is able to determine that the user is accessing the service via mobile data. This tells Discovery Service to discover using the mobile-network.\n"
    },
    "MSISDN": {
      "type": "string",
      "description": "The mobile number in [E.164 number formatting](https://en.wikipedia.org/wiki/E.164) (i.e. international dialing format) of your user if you already obtained their number in the past."
    }
  },
  "required": [
    "Redirect_URL"
  ],
  "": "http://json-schema.org/draft-04/schema#"
}

 

Examples

The following Sandbox examples can be used to get the response described below.

cURL

Copy and paste the curl command below into your command line interface

curl -v "https://discovery.sandbox.mobileconnect.io/v2/discovery" -H 'content-type: application/x-www-form-urlencoded'  -d 'Redirect_URL=https%3A%2F%2Flocalhost%2F&Selected-MCC=902&Selected-MNC=02'  -basic -u "a75e3360-c365-4126-a57b-5748ca59e899:45f2a32c-7d7d-40e2-9601-22f2ddab62de"

 

Postman

Copy the text below and import into Postman using Import → Paste Raw Text

curl -X POST \
  https://discovery.sandbox.mobileconnect.io/v2/discovery \
  -H 'authorization: Basic YTc1ZTMzNjAtYzM2NS00MTI2LWE1N2ItNTc0OGNhNTllODk5OjQ1ZjJhMzJjLTdkN2QtNDBlMi05NjAxLTIyZjJkZGFiNjJkZQ==' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'Redirect_URL=https%3A%2F%2Flocalhost%2F&Selected-MCC=902&Selected-MNC=02'

 

Response 200 OK

Headers

Content-Type: application/json

Cookies

Name Value Domain Path Expires HTTP Secure
Most-Recent-Selected-Operator 5885cafbbba12f25546a9cdf discovery.sandbox.mobileconnect.io /v2 Never true false
Most-Recent-Selected-Operator-Expiry 2017-03-08T11:24:33.921586 discovery.sandbox.mobileconnect.io /v2 Never true false

Body

{
  "subscriber_id": null,
  "ttl": 1488452073,
  "response": {
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI=",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "currency": "USD",
    "client_name": "TestApp",
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI="
  }
}

Schema

{
  "": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ttl": {
      "type": "string",
      "description": "A unix timestamp indicating the "time to live" of the response object. A timestamp in the future indicates that this response may be cached to improve performance. The `ttl` value does not have to be in the future and if it's not, the response object should not be cached.\n"
    },
    "subscriber_id": {
      "type": "string",
      "description": "    MSISDN value encoded with operator RSA certificate that can be passed along as "login_hint" parameter of the Mobile Connect API. This response value is only available when the request contains an MSISDN on the `MSISDN` parameter. The `subscriber_id` is opaque to the service provider's application in that it cannot be decypted by the application - it can only be used to pass to the mobile connect API in order to streamline the users login (potentially saving them entering an MSISDN for a second time).\n"
    },
    "response": {
      "type": "object",
      "properties": {
        "client_id": {
          "type": "string",
          "description": "00a9-4421-90d0-82cf76eba7e0 (string, required)\n\nclient_id part of your credential to be used by OIDC requests. It's important to note that this will likely not be the same as the client_id used for the discovery request and it's not safe to assume the client_id will be the same (or a variation of) the discovery request key.\n"
        },
        "client_secret": {
          "type": "string",
          "description": "4e73-4bc0-91e7-16b40cf75c67 (string, required)\n\nclient_secret part of your credential to be used by OIDC requests. Much like the `client_id`, this may be different to the discovery request credential.\n"
        },
        "serving_operator": {
          "type": "string",
          "description": "The name of the users mobile network operator (MNO)."
        },
        "country": {
          "type": "string",
          "description": "The country name in which this network operates."
        },
        "currency": {
          "type": "string",
          "description": "The currency of the serving operator."
        },
        "client_name": {
          "type": "string",
          "description": "A short app name which can be used for the `client_name` parameter on mobile connect auth requests."
        },
        "apis": {
          "type": "object",
          "properties": {
            "operatorid": {
              "type": "object",
              "properties": {
                "link": {
                  "type": "array",
                  "description": "The links describe the available endpoints for the operator. These endpoints can be used to perform mobile connect operations for the discovered MSISDN or MNC/MCC pair.\n"
                }
              },
              "required": [
                "link"
              ]
            }
          },
          "required": [
            "operatorid"
          ],
          "description": "An object describing the available interfaces for this operator which currently includes mobile connect auth related endpoints, as well as premiuminfo endpoints."
        }
      },
      "required": [
        "country",
        "currency",
        "client_name",
        "apis"
      ],
      "description": "The response object contains details of the API exchange endpoints for the MSISDN or MCC/MNC pair passed into the discovery request which are valid for the service providers application."
    }
  },
  "required": [
    "ttl",
    "response"
  ]
}

 

 

User selected MNC/MCC: ignoring cookies

GET /v2/discovery{?Selected-MCC,Selected-MNC,Ignore-Cookies}

All discovery requests are able to make use of the Ignore-Cookies flag which is intended to make testing easier in situations where there the results are likely to change.

URI Parameters

Parameter Type Required Example
Redirect_URL string Yes https://localhost/
Selected-MCC string Yes 902
Selected-MNC string Yes 02
Ignore-Cookie string Yes true

 

Request

The following uses the Sandbox

GET /v2/discovery?Redirect_URL=https://localhost&Selected-MCC=902&Selected%2DMNC=02&Ignore-Cookies=true

 

Headers

Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

 

Examples

The following Sandbox examples can be used to get the response described below.

cURL

Copy and paste the curl command below into your command line interface

curl -v "https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https://localhost/&Selected-MCC=902&Selected-MNC=02&Ignore-Cookies=true" -basic -u "a75e3360-c365-4126-a57b-5748ca59e899:45f2a32c-7d7d-40e2-9601-22f2ddab62de"

 

Postman

Copy the text below and import into Postman using Import → Paste Raw Text

curl -X GET \
  'https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https%3A%2F%2Flocalhost%2F&Selected-MCC=902&Selected-MNC=02&Ignore-Cookies=true' \
  -H 'authorization: Basic YTc1ZTMzNjAtYzM2NS00MTI2LWE1N2ItNTc0OGNhNTllODk5OjQ1ZjJhMzJjLTdkN2QtNDBlMi05NjAxLTIyZjJkZGFiNjJkZQ==' \
  -H 'cache-control: no-cache'

 

Response 200 OK

Headers

Content-Type: application/json

Body

{
  "subscriber_id": null,
  "ttl": 1488452073,
  "response": {
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI=",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "currency": "USD",
    "client_name": "TestApp",
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI="
  }
}

Schema

{
  "": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ttl": {
      "type": "string",
      "description": "A unix timestamp indicating the "time to live" of the response object. A timestamp in the future indicates that this response may be cached to improve performance. The `ttl` value does not have to be in the future and if it's not, the response object should not be cached.\n"
    },
    "subscriber_id": {
      "type": "string",
      "description": "    MSISDN value encoded with operator RSA certificate that can be passed along as "login_hint" parameter of the Mobile Connect API. This response value is only available when the request contains an MSISDN on the `MSISDN` parameter. The `subscriber_id` is opaque to the service provider's application in that it cannot be decypted by the application - it can only be used to pass to the mobile connect API in order to streamline the users login (potentially saving them entering an MSISDN for a second time).\n"
    },
    "response": {
      "type": "object",
      "properties": {
        "client_id": {
          "type": "string",
          "description": "00a9-4421-90d0-82cf76eba7e0 (string, required)\n\nclient_id part of your credential to be used by OIDC requests. It's important to note that this will likely not be the same as the client_id used for the discovery request and it's not safe to assume the client_id will be the same (or a variation of) the discovery request key.\n"
        },
        "client_secret": {
          "type": "string",
          "description": "4e73-4bc0-91e7-16b40cf75c67 (string, required)\n\nclient_secret part of your credential to be used by OIDC requests. Much like the `client_id`, this may be different to the discovery request credential.\n"
        },
        "serving_operator": {
          "type": "string",
          "description": "The name of the users mobile network operator (MNO)."
        },
        "country": {
          "type": "string",
          "description": "The country name in which this network operates."
        },
        "currency": {
          "type": "string",
          "description": "The currency of the serving operator."
        },
        "client_name": {
          "type": "string",
          "description": "A short app name which can be used for the `client_name` parameter on mobile connect auth requests."
        },
        "apis": {
          "type": "object",
          "properties": {
            "operatorid": {
              "type": "object",
              "properties": {
                "link": {
                  "type": "array",
                  "description": "The links describe the available endpoints for the operator. These endpoints can be used to perform mobile connect operations for the discovered MSISDN or MNC/MCC pair.\n"
                }
              },
              "required": [
                "link"
              ]
            }
          },
          "required": [
            "operatorid"
          ],
          "description": "An object describing the available interfaces for this operator which currently includes mobile connect auth related endpoints, as well as premiuminfo endpoints."
        }
      },
      "required": [
        "country",
        "currency",
        "client_name",
        "apis"
      ],
      "description": "The response object contains details of the API exchange endpoints for the MSISDN or MCC/MNC pair passed into the discovery request which are valid for the service providers application."
    }
  },
  "required": [
    "ttl",
    "response"
  ]
}

 

Using MSISDN POST

POST /v2/discovery

Example URI

POST https://discovery.sandbox.mobileconnect.io/v2/discovery

Request

Headers

Content-Type: application/x-www-form-urlencoded'
Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==
Accept: application/json

Body

{
  "Redirect_URL" : "http://localhost/",
  "MSISDN" : "+447700900902"
}

 

 

Response 200 OK

Headers

Content-Type: application/json

Cookies

Name Value Domain Path Expires HTTP Secure
Recent-Selected-Operator 5885cafbbba12f25546a9cdf discovery.sandbox.mobileconnect.io /v2 Never true false
Recent-Selected-Operator-Expiry 2017-03-08T11:24:33.921586 discovery.sandbox.mobileconnect.io /v2 Never true false

Body

{
{
  "ttl": 1488885934,
  "subscriber_id": "465b2a9438353af28f4e77e21757a3065916ceca7e16352eb4ca189944801605626adcafb2934e08c068f7dc86d4098fcf686854be38e9c47401c1d33de6d04aeb2f60e784e0331ab3c06867b4a7ff347f88ea9971ca07cbdb8b0b5030f3cfc74bb030da7a27dab8f3020aa54492b510161c4947d6930c4f2c79d4ffef3caaec25629f6a070fd719269c1d75b015328c7503a4f7458a2f0f011ea53770b6e6479b62d6b2424116061d5ffffd41322014e0feab3d93fbd8c7d22e6d960943d5d0b4263ec576a16631ce1a2546912782cea4718df25dd1b6b3dffa91d2fa800aa6edb63ba90afdde601e2b36be3dde0297bf66cc2f6a07fe385d7f459e4e2d63fc",
  "response": {
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI=",
    "currency": "USD",
    "client_name": "TestApp",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI="
  }
}

 

 

Response 404 Not Found

Description

The operator does not support Mobile Connect.

Headers

Content-Type: application/json

Body

{
  "error": "Not_Found_Entity",
  "description": "Operator not supported for the MSISDN supplied"
}

 

 

Response 404 Not Found

Description

The operator is not found based on MSISDN supplied.

Headers

Content-Type: application/json

Body

{
  "error": "Not_Found_Entity",
  "description": "We could not find your operator based on the MSISDN supplied"
}

 

MSISDN based with user interaction (HTML response): Part 1

GET /v2/discovery{?Redirect_URL}

A MSISDN based discovery flow requires the user to be redirected to a Mobile Connect page served by the discovery service which permits the user to enter their MSISDN or select their Operator. The first stage is to make the initial request, which will return a 302 response. If the request is to be made outside of a browser, it is possible to use the JSON response version of this call.

The response is redirected back to the application's Redirect_URL by the discovery service, again via a 302 response. URL queries are added for the mcc_mnc (a string containing the Identified-MCC and the Identified-MNC values. The response may also contain a subscriber_id which can be used in OIDC requests so that the user doesn’t have to re-type their MSISDN.

Upon receiving the request to the redirect URL, the mcc_mnc pair can be used with a basic discovery request to get the OIDC API details for the selected operator. This is described in MSISDN based with user interaction (HTML response): Part 2

URI Parameters

Parameter Type Required Example
Redirect_URL string Yes https://localhost/

 

Request

GET https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https://localhost/

Headers

Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

 

Response 302 Moved Temporarily

The first 302 response redirects the user to the web based discovery service.

Header

Location: https://discovery.sandbox.mobileconnect.io/v2/discovery/users/operator-selection?dropdown=true&session_id=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE0ODg4MTUxMjAsImV4cCI6MTQ4ODgxNjAyMCwiYXBwbGljYXRpb24iOnsiZXh0ZXJuYWxfaWQiOiI2OTUiLCJuYW1lIjoiU2FuZGJveCBUZXN0IEFwcGxpY2F0aW9uIiwiZGV2ZWxvcGVyIjp7ImVtYWlsIjoiU0h1Z2hlc0BHU01BLmNvbSIsImlkZW50aXRpZXMiOltdfSwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9sb2NhbGhvc3QiLCJrZXlzIjp7InNhbmRib3giOnsia2V5IjoiMDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmIiwic2VjcmV0IjoiYWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyIn19fSwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9sb2NhbGhvc3QvIiwiaXNzIjoic2FuZGJveC5tb2JpbGVjb25uZWN0LmlvIn0.vZ3XK_zFrfe8fdlPoUGV0_OqU6UdcgxP_gquGOoJh_c

At this point the user will interact with the Discovery Service so that the users operator can be identified.

 

Response 302 Moved Temporarily

Once the user interaction is complete then the discovery service will respond back with the operators MCC and MNC and optionally the encrypted MSISDN (subscriber_id).

Header

Location: https://localhost/?mcc_mnc=902_02&subscriber_id=170ee2c3394fb4459ea8f95cbce50753eb46ad307107da81cbebc0a36b7d5a25c79c2235f9064c0e7cc251c1356e4409f7e1bf8546c83bf6fa766313e972ea6d175cc9697e8ef732607e911442e81d41c001df9b5029aeb6c2390b5db0e464c00945cef13e9b1700d19cdb97a3765eefa2b904b02d1aa12c2a7dc663cf99901aab46b82e941725657bad200c8b5974f95c8f5341b4935cb8e67a148e96a528e6cc4e52ff81da55d728ee9c73b6795e01bd468e278ddd76a8b2d5c49741303e001a73be93e61262ac7cd42e3a123cd3c790c2f60a3ce2679b92bc9f8614bcfb917419ae4a229321bb87e16f16b8cb0539e8113b2fb45d8282ccab54588b7b87a6

 

Using the MCC & MNC sent back in the previous response the users endpoints can then be retrieved using a variant of User selected MCC/MNC with GET or User selected MCC/MNC with POST. Note that we use Identified here, not Selected.

 

Response 401 Unauthorized

If the session_id is invalid then the request fails and all cookies are reset.

Headers

Content-Type: application/json;

Body

{
    "error": "unauthorized_client",
    "description": "Your request needs a valid session or valid credentials"
}

 

MSISDN based with user interaction (HTML response): Part 2

Once the MCC and MNC have been identified by the Discovery service and returned back then they can be used to get operators endpoints

GET /v2/discovery{?Identified-MCC, Identified-MNC}

URI Parameters

Parameter Type Required Example
Identified-MCC string Yes 902
Identified-MNC string Yes 02
Redirect_URL string Yes https://localhost/

 

Request

GET https://discovery.sandbox.mobileconnect.io/v2/discovery?Identified-MCC=902&Identified-MNC=02&Redirect_URL=https://localhost/

 

Headers

Content-Type: application/json
Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

 

Response 200 OK

Headers

Content-Type: application/json

Cookies

Name Value Domain Path Expires HTTP Secure
Most-Recent-Selected-Operator 5885cafbbba12f25546a9cdf discovery.sandbox.mobileconnect.io /v2 Never true false
Most-Recent-Selected-Operator-Expiry 2017-03-08T11:24:33.921586 discovery.sandbox.mobileconnect.io /v2 Never true false

Body

{
  "ttl": 1488891354,
  "subscriber_id": "",
  "response": {
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI=",
    "currency": "USD",
    "client_name": "TestApp",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI="
  }
}

 

MSISDN based with user interaction (JSON response)

By adding an Accept header to the initial request the user interaction details will be returned as a JSON structure rather than as an HTML 302 response.

GET /v2/discovery{?Redirect_URL}

Example URI

GET /v2/discovery?Redirect_URL=https:/example.com/discovered

URI Parameters

Redirect_URL string (required) Example: https://example.com/discovered

Request Discovery

Headers

Authorization: Basic ZmU0NDY1NDEtOTJmNy00MmVlLThjMzYtNTM0YmM4NmNmNWQ0OjU0NzY0YTcyLWFkNDQtNDlhZC04OTllLTI0OThlODdmYzdkZA==
Accept: application/json

 

Response 200 OK

Headers

Content-Type: application/json

Body

{
  "links": [
    {
      "href": "https://discover.mobileconnect.io/sb1/v2/discovery/users/operator",
      "rel": "operatorSelection"
    }
  ]
}

Schema

{
  "": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "links": {
      "type": "array",
      "description": "The links array contains a single link which should be opened in a web view in order to allow the user to complete the discovery steps.\n"
    }
  }
}

The operator selection screen can then be requested by the application, allowing the user to interact with the discovery service. Once the response is returned then the operator details can be returned as detailed in MSISDN based with user interaction (HTML response): Part 2.

 

MSISDN based with user interaction and errors returned to the application

GET /v2/discovery{?Redirect_URL,X-Redirect}

A user interaction based discovery flow requires the user to be redirected to a Mobile Connect web page served by the discovery service which permits them to enter their MSISDN or select their operator. Normally any errors messages generated by the discovery user interface are displayed within this UI. It is possible to have any errors returned as standard JSON errors rather displayed in the discovery interface.

To enable these JSON error messages use the X-Redirect parameter in your initial request.

Parameter Type Required Example
Redirect_URL string Yes https://localhost/
X-Redirect string No APP

 

Request

GET https://discovery.sandbox.mobileconnect.io/v2/discovery?Redirect_URL=https://localhost/&X-Redirect=APP

Headers

Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

The flow will then proceed as normal for either an HTML response or JSON response unless an error occurs. If so then the error response will be returned as a standard JSON error response, example below

 

Response 404 Not Found

Description

The MCC/MNC pairing does not match an operator

Headers

Content-Type: application/json

Body

{
  "error": "Not_Found_Entity",
  "description": "There is no organization with the specified mcc/mnc pair"
}

 

Developer app sends MSISDN

POST /v2/discovery

Example URI

POST /v2/discovery

Request

Headers

Authorization: Basic ZmU0NDY1NDEtOTJmNy00MmVlLThjMzYtNTM0YmM4NmNmNWQ0OjU0NzY0YTcyLWFkNDQtNDlhZC04OTllLTI0OThlODdmYzdkZA==

Body

{
  "Redirect_URL": "https://localhost/discovered.html",
   "MSISDN": "+44234567890"
}

 

Response 200 OK

Direct discovery response with cookies set. Also note the subscriber_id parameter in the response payload

Headers

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Origin, X-Requested-With, X-Source-Ip, Accept, Authorization, User-Agent, Host, Accept-Language, Location, Referer, Set-Cookie
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Credentials: true
Content-Type: application/json; charset=utf-8

Body

{
  "ttl": 1418876992275,
  "response": {
    "client_id": "XQNdLefAgGSgmcLAUl6RQvOxQOVAawXh",
    "client_secret": "biZoSofpT5lqwdvw",
    "subscriber_operator": "etelco_demo",
    "country": "US",
    "currency": "USD",
    "apis": {
      "messaging": {
        "link": [
          {
            "href": "http://example.url/sandbox/sacl/smsmessaging/v1/outbound/{senderAddress}/requests",
            "rel": "uri"
          },
          {
            "href": "GET,POST-/messaging/acr:Authorization/sendsms",
            "rel": "scope"
          }
        ]
      },
      "payment": {
        "link": [
          {
            "href": "http://example.url/v1/payment/acr:Authorization/transactions/amountReservation",
            "rel": "reserve"
          },
          {
            "href": "https://example.url/v1/payment/acr:Authorization/transactions/amount",
            "rel": "transactionstatus"
          },
          {
            "href": "http://example.url/v1/payment/acr:Authorization/transactions/amount",
            "rel": "charge"
          },
          {
            "href": "GET,POST-/payment/acr:Authorization/transactions/amount",
            "rel": "scope"
          }
        ]
      }
    }
  },
  "subscriber_id": "119376fe412e3754aacc1fbcc97fdeff617fdeb475358858c412fe51f497430ac7405219ecd45c500352331d20ae13f893ace5b1b6a0873179b4f9e5c78f7815c2d87005fb65578264a532a7b9c656d00d30a6aa86330b32e59d86e111befbb39228250d60a12021bf88e55c2b0afa62cb81a277f3b72a27f7af346db020410552fb88eea0cc611a1187751acfa7a7ba20750efe79b32e19a36271f8a9b9314b09d665e99748e4d857a1a73f29bb156fdf93ad319bef1179af01fa95def72b1dfddcd1cc35c2977ac14b8eac7165f144caf2f4d6f8b55f1998b018fbd140c2c233d1473dfc996edbe0f75875f3df7fe03c710fe8de2f4a3cef8d419f26fa874e"
}

 

IP based using mobile data

GET /v2/discovery?Redirect_URL

In cases where there is a server/client application and the server is making the Discovery request then the server application can pick up the clients IP address and use it in the request. This will allow the Discovery service to attempt identify the users operator using their IP address. The Using-Mobile-Data header should also be set to 'true’.

This functionality can be tested with the Sandbox using the the test operator IP addresses defined here.

NOTE: If this is used with other parameters (such as Selected-MCC/MNC) then this will be ignored.

Example URI

GET /v2/discovery?Redirect_URL=https:/localhost&X-Source-IP=10.0.0.2

URI Parameters

Redirect_URL string (required) Example: https://example.com/discovered

X-Source-IP string (optional) Example: 10.0.0.2

Request

Headers

Content-Type: application/json
Authorization: Basic MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOmFiMjZkMmJkLTAzMTItNDE4OC1iYzA4LWE1MjdmYTFjMGQyMg==

 

Response 200 OK

Body

{
  "subscriber_id": null,
  "ttl": 1488452073,
  "response": {
    "serving_operator": "Example Operator B",
    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN2ZhMWMwZDIyOm9wZXJhdG9yLWI=",
    "country": "US",
    "apis": {
      "operatorid": {
        "link": [
          {
            "rel": "authorization",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/authorize"
          },
          {
            "rel": "token",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/accesstoken"
          },
          {
            "rel": "userinfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/userinfo"
          },
          {
            "rel": "tokenrevoke",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/revoke"
          },
          {
            "rel": "premiuminfo",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/premiuminfo"
          },
          {
            "rel": "scope",
            "href": "openid profile email"
          },
          {
            "rel": "openid-configuration",
            "href": "https://operator-b.sandbox.mobileconnect.io/.well-known/openid-configuration"
          },
          {
            "rel": "jwks",
            "href": "https://operator-b.sandbox.mobileconnect.io/oidc/operator-b/jwks.json"
          }
        ]
      }
    },
    "currency": "USD",
    "client_name": "TestApp",
    "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhYjZmOm9wZXJhdG9yLWI="
  }
}