Network API Authentication
To use the Network APIs, you need to create an access token; to do this, you must follow these steps:
- Link Your Network Profile to a Vonage Application: Create a Vonage application and link the network registration profile created for you as part of the registration process.
- Generate a JWT: To make the requests to create the access token, you'll need a JWT.
- Generate an Access Token: Follow the Back-End Authentication flow to generate an access token for the API you will be using.
Link Your Network Profile to a Vonage Application
Once your registration is approved, the Network APIs will be enabled in your Vonage account. As a part of this process, a Network Application Profile will be created for you - this must be linked to a Vonage application.
Create an application by heading to the Applications page on the customer dashboard and clicking 'Create a new application'.
Under 'Capabilities', you'll find Network APIs; enable this to select the business profile and network application profile that were created for your account.
Generate a JWT
To create an access token, you'll first need to generate a JWT, referred to throughout this guide as $JWT_AP. You can use our online generator to create a JWT using your private key and the ID of the application you created in the previous step, both found in the developer dashboard, or follow the instructions here to use another method.
Once you've generated your JWT, follow the next step to start the back-end authentication flow.
Back-End Authentication Flow
1. Make an OIDC Request
https://api-eu.vonage.com/oauth2/bc-authorizeParameters
| Parameter | Description |
|---|---|
login_hint | Must be set to tel:+<MSISDN>, where MSISDN is the phone number (including country code) you wish to check, e.g. tel:+447700900000 |
scope | A string in the format openid dpv:<purpose>#<api-scope>, where:purpose describes the purpose for which you are calling the API. The available purposes are listed in Network API Purposes.api-scope is taken from the Authentication section in the API specification for the operation of the Network API being invoked.For example, the scope parameter for the SIM Swap API when using the check operation for the purpose of 'Fraud Prevention and Detection' would be openid dpv:FraudPreventionAndDetection#check-sim-swap. If using the Device Status API to check connectivity status, the scope would be openid dpv:NotApplicable#device-status:connectivity:read. |
Successful Response
Here, expires_in (required) is the number of seconds until the authentication code expires, and interval (optional) is the number of seconds until the next request should be made. You'll need the auth_req_id for the next step.
2. Make a POST request to get a CAMARA Access Token
https://api-eu.vonage.com/oauth2/tokenParameters
| Parameter | Description |
|---|---|
auth_req_id | This is provided in the response of Step 1. |
grant_type | Should be set to urn:openid:params:grant-type:ciba. |
Successful Token Response
The access token received here can now be used to run a SIM Swap or Device Status against the MSISDN specified in the OIDC request. If you want to run a check against a different number, you must generate a new access token for that number.