Additional Information | Vodafone Developer Marketplace

Select the Correct Mobile Network Operator

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) you want to query. This ensures API requests are efficiently directed to the correct MNO. This service is not provided by Vodafone.

A Three-legged OAuth Flow

SIM Swap (CAMARA) 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
Call the SIM Swap resource API

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

Get an Authorization Code

Make a request to Vodafone’s “/bc-authorize” endpoint.
Vodafone's API validates the client_id provided.
Vodafone obtains the mobile number 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

POST https://apistagingref.developer.vodafone.com/openIDConnectCIBA/v1/bcauthorize
Content-Type: application/x-www-form-urlencoded
Authorization: Basic
d3lCOHF1R0RPWTdXTnUyVUV2eGF5Sk9aNVpTSU1KM1Y6V2ZHQUJqSUJpRDIySg==
X-Correlator: f28b7f31-e06b-426d-b563-aec3c4ade049
vf-trace-transaction-id: aaaef4cf-1212-4009-8e25-4bcad9a9b206
vf_ext_bp_id: Acme_Co
login_hint=tel%3A%2B447123456789
scope=openid%20check-sim-swap

Authorization response example

HTTP/1.1 200 OK
Date: Tue, 03 Oct 2023 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-Type: application/json
Content-Length: xx.
X-Correlator: f28b7f31-e06b-426d-b563-aec3c4ade049
vf-trace-transaction-id: aaaef4cf-1212-4009-8e25-4bcad9a9b206
{
"auth_req_id": "39da5b19-457a-4d30-a5c4-047c62dcca3b",
"expires_in": 300,
"interval": 0
}

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://eu3.api.vodafone.com/openIDConnectCIBA/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://stagingref.eu3.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"
}

Using the Sandbox

Use the following MSISDN and format in the Sandbox:

tel:+447123456789

This number will provide a true response that the SIM has been swapped.

{
    "swapped": true
}

SIM Swap (CAMARA)