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|
In this document you can learn about authentication via the following means:
When you create a Nexmo account you will be provided an API key and an API secret. The API key is used to identify the Nexmo account and the API secret is used to verify the identity. These can be found in your account settings in the Nexmo Dashboard.
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 parameters of requests you make to the Conversion, Number Insight or Developer API.
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
- 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 supported by the Voice API as a means of authenticating 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. Minimum time of 30 seconds from the time the JWT is generated. Maximim value of 24 hours from the time the JWT is generated. Default value of 15 minutes from the time the JWT is generation.|
If you are not using a Nexmo library you should refer to RFC 7519 to implement JWT.
Some Nexmo APIs support OAuth as a means of authenticating. We provide an in-depth guide on how to authenticate with OAuth here.