Server Authentication

Prerequisites

This guide assumes you have completed the following requirements:

Network APIs capability is enabled in your Vonage application. Follow this guide to read detailed information on how to do it.
You have a valid JWT. You can use our online generator to create a JWT using your private key and the ID of your Vonage application, both found in the customer dashboard, or follow the instructions here to use another method.

Auth API Reference

The OpenAPI specification for the Network API auth endpoints is available here.

Authentication Flow

Making an API call is a three-step process:

The backend application requests an authorization id.
The backend application uses that authorization id to request a CAMARA access token.
Finally, the backend application uses the access token to make the API call.

Make an OIDC Request

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol, which provides a way to verify a user's identity using the JWT token.

POST

https://api-eu.vonage.com/oauth2/bc-authorize

  curl --request POST \
  --url https://api-eu.vonage.com/oauth2/bc-authorize \
  --header 'Authorization: Bearer $JWT' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'login_hint=$PHONE_NUMBER' \
  --data 'scope=openid dpv:purpose#api-scope'

Headers

Header	Description
`Authorization`	Must be set to `Bearer` along with the `JWT` token generated in the previous step. The `JWT` must correlate to the App that is approved for the Network APIs usage.
`Content-Type`	Must be set to `application/x-www-form-urlencoded`.

Body Parameters

Parameter	Description
`login_hint`	(Required) The phone number (including country code) you wish to check, e.g. `+447700900000`
`scope`	(Required) Scope in string format. For more details, refer to the scope guide.

If you want to make an API call against a different phone number, you must generate a new access token for that number.

Response

On success, the response will have a 200 OK status and the following JSON data in the response body:

{
  "auth_req_id": "$AUTH_REQ_ID",
  "expires_in": 120,
  "interval": 2
}

Parameter	Type	Description
`auth_req_id`	string	The authorization id string you'll need for the next step.
`expires_in`	int	The number of seconds until the authentication code expires
`interval`	int	The number of seconds until the next request should be made

Request a CAMARA Access Token

To request a CAMARA access token, send a

POST

request to https://api-eu.vonage.com/oauth2/token

  curl --request POST \
    --url https://api-eu.vonage.com/oauth2/token \
    --header 'Authorization: Bearer $JWT' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data auth_req_id=$AUTH_REQ_ID \
    --data grant_type=urn:openid:params:grant-type:ciba

Headers

Header	Description
`Authorization`	Must be set to `Bearer` along with the `JWT` token generated in the previous step. The `JWT` must correlate to the App that is approved for the Network APIs usage.
`Content-Type`	Must be set to `application/x-www-form-urlencoded`.

Body Parameters

Parameter	Description
`auth_req_id`	(Required) This is provided in the response of the previous step.
`grant_type`	(Required) Must be set to `urn:openid:params:grant-type:ciba`.

Response

On success, the response will have a 200 OK status and the following JSON data in the response body:

{
 "access_token": "$ACCESS_TOKEN",
 "token_type": "Bearer",
 "expires_in": 3600
}

Parameter	Type	Description
`access_token`	string	The access token that will be used during the API calls.
`token_type`	string	It is always set to `Bearer`.
`expires_in`	int	The time period (in seconds) for which the access token is valid.

Make the API call

All Network API calls must contain the following header:

Header	Description
`Authorization`	Must be set to `Bearer` along with the `access token` generated in the previous step.