Additional Information | Vodafone Developer Marketplace

Using a three-legged OAuth flow

Number Verify uses a three-legged OAuth flow. A three-legged OAuth process involves three parties: the end-user (or resource owner), the client (the third-party application), and the server (or authorization server):

Get an authorization code
Exchange the authorization code for an access token
Match the mobile number

For more information on OAuth, see OAuth 2.0 RFC 6749, section 4.1 (external website).

Select the correct MNO for the mobile number

You must use a discovery service to determine which Mobile Network Operator's (MNO's) API you should use for each individual mobile number (MSISDN). This ensures API requests are efficiently directed to the correct MNO. This service is not provided by Vodafone.

Get an authorization code

Make a request to Vodafone's "/authorize" endpoint.
Vodafone's API validates the client_id provided.
Vodafone obtains the mobile number (MSISDN) of the user (of the application using the mobile network).
This is achieved by the Vodafone returning a series of HTTP redirects that the application should follow.
Vodafone provides an authorization code back to the application.

Authorization request example

GET 'https://eu2-stagingref.api.vodafone.com/mobileconnect/deviceinitiated/v1/authorize' \
Content-Type: application/x-www-form-urlencoded \
Accept: application/json \
redirect_uri=https%3A%2F%2Fexample.com%2Fmc &client_id=asQIujGX4tD9eBMgeO8LnzyRnalkTGoG &scope=openid+mc_vm_match_hash &response_type=code
&state=af0ifjsldkj
&acr_values=2
&nonce=abcdefghijklmno &correlation_id=42da5b19-457a-4d30-a5c4-038c62dccbb0 &version=mc_di_r2_v2.3

Authorization response example

HTTP/1.1 302 Found
Location: https://sp.example.com?code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj &correlation_id=42da5b19-457a-4d30-a5c4-038c62dccbb0

Get an access token

In order to use this API, you must exchange the authorization code for an access token.

The token is valid for 59 minutes and 59 seconds. It can be used for multiple requests.

The bearer tokens can only be used for a specific country. For example: If you generate a token for a UK mobile number (MSISDN), you cannot use it to query a German number.

If the request is valid, the API returns an access_token, along with expiry and scope information.

This access token can then be used in one or more requests, for as long as the token remains valid.

If the request is not valid, the APIs returns an error message.

To exchange the authorization code for an access token:

Make a "/token" request.
Validate the "id_token" within the response. This to ensure it was issued from the correct authorization server, the correct client_id, and in a timely manner.

Token request example

curl POST 'https://eu2-stagingref.api.vodafone.com/mobileconnect/deviceinitiated/v1/token' 
Authorization: Basic ZTcxNWE2OTYtYTY3OS00YmFhLTk3ODctYTU0ZmYlMTFhNmQ4OjdhMzM3OGI5LWZkMTQtNGNhYy1hZTc 3LTkwZGVmZmZkYWQ5Yg==
code=w4tngz6O&state=1234&redirect_uri=https://sp.example.com &grant_type=authorization_code

Token response example

200 OK
Server: VF
Content-Type: application/json
Content-Length: 165
Cache-Control: no-store
Pragma: no-cache.
Content-Length: xx.
Content-Type: application/json
{
"access_token": "OohPZluqx9NYtkTA3Ok6yfRmIECi", "token_type": "Bearer",
 "expires_in": 3599,
"id_token": "eyJraWQiOiJhcGl4IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoia0V3dzB SdF81dk8tZGo5UjFoY0dlQSIsInN1YiI6IjZmODVjM2EyLTRlY2EtNGM4Yy1hNDI4LWQ0NjNlNmIxNz NmNiIsImNyaWQiOiIyOTQ4NDUyNSIsImFtciI6WyJTTVNfVVJMX09LIl0sImlzcyI6Imh0dHBzOi8vY XBpc3RhZ2luZ3JlZi5kZXZlbG9wZXIudm9kYWZvbmUuY29tIiwibm9uY2UiOiIxMjM0NTY3OCIsImF1 ZCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZTExYTZkOCIsImFjciI6InVybjp2b2RhZm9 uZTpsb2E6YnJvbnplOnNtc3VybCIsImF6cCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZT ExYTZkOCIsImF1dGhfdGltZSI6IjE1NjUzNTI3MjAiLCJleHAiOjE1NjUzNTYzNjgsImlhdCI6MTU2N TM1Mjc2OCwianRpIjoiNGFlMTJlNzMtMDY4Yi00ZTUyLWJmMmMtOWUyNjdiNGQ3NDNmIn0.U3MO6FFr 3l0G6_TvmlbpGyxVPxZKCQyvB_1J5TFeA8Jlx7KhE1nf9LDVw22eX2X6- 1ogqKLGXl_4Q3ou0p_lMk2z8uFGulHB4Xv51qAMdLwA9XPfoW7j2fVaoRdjSDWQbNpurpyC0sHWsSJt -
O4SP_All1_PTtv8MBlIPJyLpFsSU3cAnbQcXQ8NQ5FqNfAlgj11ejsxBOzr8UaT0wYMOCapz8V89FmQ 9F7fj- YpNoco4r8G_KSkjjbSWL4FdTbxTQ2iBNAKtoaTN2bmbVfUaADMJDDdTeLTJerpNbi4LVlqkvhKiSWzI UOBf_10FKt4KUffnx4AK_IAvS49nwwt5w"
}

Decoding the id_token gives the following JWT header and payload:

{
  "kid": "apix",
  "typ": "JWT",
  "alg": "RS256"
} {
"at_hash": "kEww0Rt_5vO-dj9R1hcGeA",
"sub": "6f85c3a2-4eca-4c8c-a428-d463e6b173f6", "amr": [
"SEAM_OK" ],
"iss": "https://eu2-stagingref.api.vodafone.com", "nonce": "12345678",
"aud": "e715a696-a679-4baa-9787-a54ffe11a6d8", "acr": "2",
"azp": "e715a696-a679-4baa-9787-a54ffe11a6d8", "auth_time": "1565352720",
"exp": 1565356368,
"iat": 1565352768,
"jti": "4ae12e73-068b-4e52-bf2c-9e267b4d743f"
}

Match the mobile number

Use the access token to make a "/premiuminfo" request to the Vodafone ID Gateway (IDGW). To match the mobile number (MSISDN), you must provide a mobile number in the request.
Vodafone determines the result of the Number Verify transaction.
The result of the Number Verify transaction is stored before the response to the "/premiuminfo" request is returned.
Vodafone sends the response.

Endpoint request example

This example is for mobile number "+447767787999":

curl POST 'https://eu2-stagingref.api.vodafone.com/mobileconnect/premiuminfo/v1/'
Authorization: Bearer LTRjZDMtNDUyYi1iNjk
{
"mc_claims" : {
"device_msisdn_hash" :
"73e5578761e35869a6a97cc9a30d93f32c695c82aa4aa0e6cbdffadb52f5ac8c" },
"correlation_id" : "TEST_CORRELATION_ID" }

The attributes must be sent in hashed format: SHA-256 hash in hexadecimal format, lower-case. The mobile number must be prefixed with "+" and the country international dialling prefix.

Response example

Below is an example response. In this situation, the mobile number provided did not match the number stored in the Vodafone database:

HTTP/1.1 200 OK.
Date: Tue, 03 Oct 2017 09:37:43 GMT.
Server: XXXXXXX
Expires: Thu, 19 Nov 1981 08:52:00 GMT.
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0. Pragma: no-cache.
Content-Length: xx.
{
"sub": "cd45a691-d311-4134-9a0c-2747e5110d22", "device_msisdn_verified": false, "correlation_id": "TEST_CORRELATION_ID"
}

About the JWKS endpoint

The JWKS endpoint (GET/jwks) is an unprotected resource that returns one or more keys for creating a certificate. The certificate is used for creating a signature and verifying the signature of the id_token in the /token response.

There are no headers or parameters required.

To verify the id_token JWT signature, the JWK entry with "kid" of the same value as that of the "kid" value in the JWT must be selected.

Sample request

GET 'https://eu2-stagingref.api.vodafone.com/jwks/v1/'

Sample response

HTTP/1.1 200 OK.
Content-Type: application/json
Content-Length: xx
Cache-Control: no-store
Pragma: no-cache
Expires: 2019-08-09T15:25:26.552Z
{
"keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "kid": "apix",
      "kty": "RSA",
"n": "2UBTaJAFzGYaKCEtM35k6InOAEWQUBnMcgfpKZgsoP0qD- 9KllFjtb7IXjXI1mOkeix8aovdzC40oJ0BoATtgFQ5UgDeA6vel2mKaGrQJn8iLeTO1RvVRioUmR_wK YjciUFmCKpRHfmBDtgtQYcj2bfrugpgnn4_3ple3I67KuwZcZyIM- jxVP87kwXUklRuHAaz3jK7UMfCWYx1q8PFR7uLxu4ZEJmubg3cKwbsqfTtSLZ33BoyzIpFE2ClNLsUp EGNQpZHgL18pz4Yu2O42Z62FJvG9M-46A3RK3N84bAJ2wvM7iOJTBy3AcxxRGSO- ws_zylOBozpl5EVPVUu2w",
      "use": "sig"
    },
    {
      "alg": "RS256",
      "e": "AQAB",
      "kid": "dummy",
            "kty": "RSA",
"n": "m0vdQFEeO8BRrleqpSiBKaOMGQOY6fjOn4hyOkSfHg3LDNDJ4IENBk6mV1nAOXgb9mIPvhWxr_A7nb ISwjfQKLeBHLk8VP3_KxaGPd70yG1AokkBg8lswRPecM3y_YKFc8n97Yhg3cioXwhs- uV6M2YSkgOskjm8uRbk- d25j4eNc9MSe1U7pZ4fBuKPQok9Wxqkn_Pr9UlZchlW6Sl04vN5N6CSHbhvfiI64V_gWLG8Iz2ary9z aoFBfsDlphp-w1sHgxTlsONp1DpsR4l9V_JSefD-dgBs-w4y9VuxG1Lu5P- a8Ym488UaaJrlbPsCH0ek9aBgGSUq-E1d-5tq_Q",
      "use": "enc"
    }
]

Number Verify