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)|
In this document you can learn about authentication via the following means:
- API Key and Secret
- JSON Web Tokens (JWT)
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 these details: be careful when adding it to your codebase to make sure they are not shared with anyone who may use it maliciously. If you use message signatures, these are generated using the
SIGNATURE_SECRET rather than the
API_SECRET; both values can be found in your account settings.
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.
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.
Your API key and secret should be included in the query parameters of requests you make to the Conversion, Number Insight or Developer API. The parameters are called
An example of authentication query parameters would be as follows:
The request may also need other query parameters and these can be added in any order.
A number of newer Nexmo APIs require authentication to be done using an API key and secret sent Base64 encoded in the
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:
- General: Base64 Encode and Decode
Details on how to encode Base64 strings in a variety of programming languages can be found at the following websites:
- C#/.NET: How do I encode and decode a Base64 string? from StackOverflow
- Go: Base64 Encoding from Go By Example
- Java: Base64
- PHP: base64_encode
- Python: Base64
- Ruby: Base64
- Swift: Base64 Encode and Decode in Swift from iOS Developer Tips
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:
- Create a second API secret in your account settings or by using the secret rotation API.
- Update one or more of your servers to use the newly created API secret for making calls to Nexmo APIs
- Test that there are no connectivity issues and roll out the API secret update across the remaining servers
- Delete the replaced API secret
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:
||The encryption algorithm used to generate the JWT.
||The token structure. Set to
The values for the payload claim are:
||The unique ID allocated to your application by Nexmo.|
||The UNIX timestamp at UTC + 0 indicating the moment the JWT was requested.|
||The unique ID of the JWT.|
||The UNIX timestamp at UTC + 0 indicating the moment the JWT became valid.|
||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.