Authentication

Nexmo API provides various means of Authentication depending on what product you are using.

API API Key and Secret (Query String) API Key and Secret (Header) JSON Web Token (JWT) OAuth
SMS
Voice
Verify
Number Insight
Conversion
Developer
Messages
Dispatch
Audit
Redact

Contents

In this document you can learn about authentication via the following means:

API Key and Secret

When you create a Nexmo account, an API key and secret will be created for you. These are located in your account settings  in the Nexmo Dashboard. You should always keep these secure and never share them: be careful when adding it to your codebase to make sure they are not shared with anyone who may use it maliciously.

Note: The secret should always be kept secure and never shared. Be careful when adding it to your codebase to make sure it is not shared with anyone who may use it maliciously. Read more about the Best Security Practices for your Nexmo Account  .

Nexmo APIs may require your API Key and Secret in a number of different ways.

Request Body

For POST requests to the SMS API, your API key and secret should be sent as part of the body of the request in the JSON object.

Query String

Your API key and secret should be included in the parameters of requests you make to the Conversion, Number Insight or Developer API.

Header-based API Key and Secret Authentication

A number of newer Nexmo APIs require authentication to be done using an API key and secret sent Base64-encoded in the Authorization header.

For these APIs, you send your API key and secret in the following way:

Authorization: Basic base64(API_KEY:API_SECRET)

If your API key were aaa012 and your API secret were abc123456789, you would concatenate the key and secret with a : (colon) symbol and then encode them using Base64 encoding to produce a value like this:

Authorization: Basic YWFhMDEyOmFiYzEyMzQ1Njc4OQ==

A website for generating Base64 encoded strings can be found here:

Details on how to encode Base64 strings in a variety of programming languages can be found at the following websites:

Secret Rotation

It is possible to have two API secrets to be used against one API key at the same time. This way you can create a second API secret and test it before revoking the existing API secret in your production network. The API secret rotation procedure consists of the following steps:

  1. Create a second API secret in your account settings  or by using the secret rotation API.
  2. Update one or more of your servers to use the newly created API secret for making calls to Nexmo APIs
  3. Test that there are no connectivity issues and roll out the API secret update across the remaining servers
  4. Delete the replaced API secret

JSON Web Tokens (JWT)

JSON Web Tokens (JWT) are a compact, URL-safe means of representing claims to be transferred between two parties.

JWTs are used by the Voice API to authenticate your requests. The Nexmo libraries and CLI handle JWT generation using a unique Nexmo Voice Application ID and a Private Key.

Values for the Header are:

Name Description Required
alg The encryption algorithm used to generate the JWT. RS256 is supported.
typ The token structure. Set to JWT.

The values for the payload claim are:

Name Description Required
application_id The unique ID allocated to your application by Nexmo.
iat The UNIX timestamp at UTC + 0 indicating the moment the JWT was requested.
jti The unique ID of the JWT.
nbf The UNIX timestamp at UTC + 0 indicating the moment the JWT became valid.
exp The UNIX timestamp at UTC + 0 indicating the moment the JWT is no longer valid. A minimum value of 30 seconds from the time the JWT is generated. A maximum value of 24 hours from the time the JWT is generated. A default value of 15 minutes from the time the JWT is generated.

If you are not using a Nexmo library you should refer to RFC 7519  to implement JWT.

OAuth

Some Nexmo APIs support OAuth as an authentication option. We provide an in-depth guide on how to authenticate with OAuth here.

References