Authentication

Not a developer?

Verifalia makes email verification and mailing list cleaning easy: just upload your list, and you'll get a detailed report. Learn more

Core concepts

Verifying email addresses

Authentication

Authentication to the Verifalia API is performed by way of either the credentials of your root Verifalia account or of one of its users (previously known as sub-accounts).

For security reasons, it is always advisable to create and use a dedicated user for accessing the API, as doing so will allow to assign only the specific needed permissions to it. You can easily create a new user from your Verifalia dashboard ( Users pane).

Add a new user

Authentication to the API occurs via one of the methods described hereafter.

HTTP Basic Auth

Requires the API consumer to provide the user-name and password of either a Verifalia root account (inadvisable for security reasons, see above) or a user bound to an account, by way of the Authorization HTTP header, according to the RFC 7617. This method requires the API consumer to send the credentials for each request.

Authenticate via HTTP Basic Auth
Language:

curl -u username:password \
    https://api.verifalia.com/v2.6/...

using Verifalia.Api;
// ...
var verifalia = new VerifaliaRestClient("username", "password");

import com.verifalia.api.VerifaliaRestClient;
// ...
VerifaliaRestClient verifalia =
    new VerifaliaRestClient("user", "password");

const { VerifaliaRestClient } = require('verifalia');

const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::USERNAME => 'your-username-here',
    VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);

package main

import (
    "github.com/verifalia/verifalia-go-sdk/verifalia"
)

func main() {
    client := verifalia.NewClient("username", "password")

    // TODO: Use "client"
}

require 'verifalia'

# ...

verifalia = Verifalia::Client.new username: 'user', password: 'password'

Bearer authentication

Under this method Verifalia provides you with an encrypted security token (called bearer token) in response to a first authentication request, using the user-name and password of either your Verifalia root account (inadvisable for security reasons, see above) or a user bound to your account; the API consumer must then send that encrypted security token while making subsequent requests.

Bearer authentication offers higher security over HTTP Basic Auth, as the latter requires sending the actual credentials on each API call, while the former only requires it on a first, dedicated authentication request. On the other side, the first authentication request needed by Bearer authentication takes a non-negligible time: if the API consumer needs to perform only one request, using HTTP Basic Auth provides the same degree of security and is the faster option too.

v2.6+ The bearer tokens provided by Verifalia are JSON Web Tokens (JWTs), adhering to the open standard defined by RFC 7519; this standard offers a concise and self-contained method for securely transmitting information between parties in the form of a JSON object. The JSON object structure contains several fields the standard calls claims, including sub, exp, and verifalia:mfa - as documented below; additionally, it may contain other fields subject to change that API consumers must ignore.

sub

Identifies the principal that is the subject of the JWT and contains the ID of the Verifalia user (not to be confused with the user name or with the account ID).

exp

Identifies the expiration time on or after which the bearer token will not be accepted for processing; it is serialized as the number of seconds since Epoch.

verifalia:mfa

This custom claim is only returned when the user needs to utilize an additional authentication factor to finalize the authentication process; it includes an array listing the supported authentication factors. The supported value is totp, signaling the availability of a Time-Based One-Time Password (TOTP) factor; any other value may change and must be ignored by API consumers.

To request a bearer token, API consumers must issue an HTTP POST request along with a JSON object containing the user credentials against this sub-resource:

/auth/tokens

The posted JSON object must have structure shown hereafter.

JSON structure (request)

Property	Description
`username`	A `string` with the username of the requesting Verifalia user (or root account - please see the security note above).
`password`	A `string` with the password of the requesting Verifalia user (or root account - please see the security note above).

In response to the authentication request, Verifalia replies with either an HTTP 200 (OK) status code, meaning the operation completed successfully, or with an HTTP 401 (Unauthorized) status code.

Upon successful completion, the API returns a JSON object with a time-limited bearer token which represents the authenticated user.

JSON structure (response)

Property	Description
`accessToken`	A `string` representing the bearer token for the authenticated user.

Request a bearer token
Language:

curl -H "Content-Type: application/json" \
    -d '{ "username": "samantha", "password": "42istheanswer" }' \
    https://api.verifalia.com/v2.6/auth/tokens

var verifalia = new VerifaliaRestClient(
    new BearerAuthenticationProvider("username", "password"));

// ...
// The SDK will automatically retrieve a bearer token on the first
// API invocation.

BearerAuthenticationProvider authProvider =
    new BearerAuthenticationProvider("username", "password");

VerifaliaRestClient verifalia =
    new VerifaliaRestClient(authProvider);

// ...
// The SDK will automatically retrieve a bearer token on the first
// API invocation.

// The Javascript SDK does not support this feature yet.

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
use Verifalia\Security\BearerAuthenticationProvider;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::AUTHENTICATION_PROVIDER => 
        new BearerAuthenticationProvider('your-username-here',
            'your-password-here')
]);

// The Go SDK does not support this feature yet.

# The Ruby SDK does not support this feature yet.

On subsequent API calls, the API consumer must pass the bearer token obtained during the first call above by way of the Authorization HTTP header, according to the RFC 7617.

Use the obtained bearer token
Language:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1...JV_adQssw5c" \
    https://api.verifalia.com/v2.6/...

// The .NET SDK automatically uses bearer tokens, no need to pass
// them explicitly.

// The Java SDK automatically uses bearer tokens, no need to pass
// them explicitly.

// The Javascript SDK does not support this feature yet.

// The PHP SDK automatically uses bearer tokens, no need to pass
// them explicitly.

// The Go SDK does not support this feature yet.

# The Ruby SDK does not support this feature yet.

Multi-Factor Authentication (MFA) v2.6+

As mentioned before, when the user has to finalize the authentication process with a secondary factor, the API provides a JWT bearer token that contains the claim verifalia:mfa, which lists the enrolled factors for the user. After receiving a bearer token upon authentication, the API consumer needs to verify the presence of that claim and choose one of the provided authentication factors as outlined below. If the API consumer doesn't support any of the offered factors, the authentication process should be stopped.

Time-Based One-Time Password (TOTP)

A Time-Based One-Time Password (TOTP) is a type of authentication method which generates a unique, temporary passcode that changes periodically, typically every 30 seconds; TOTP relies on a shared secret key, usually stored on both the server and the user's device / smartphone. The API indicates that TOTP is available for use as an authentication factor by including the string totp in the verifalia:mfa claim array.

To complete the authentication process using TOTP, API consumers must issue a POST request against this sub-resource:

/auth/totp/verifications

The posted JSON object must have structure shown hereafter.

JSON structure (request)

Property	Description
`passCode`	A `string` with the one-time password generated by the user's device / smartphone.

In response to a successful step-up authentication request, Verifalia replies with an HTTP 200 (OK) status code and returns a JSON object with a time-limited bearer token which represents the authenticated user.

Language:

curl -H "Content-Type: application/json" \
    -d '{ "passCode": "123456" }' \
    https://api.verifalia.com/v2.6/auth/totp/verifications

using Verifalia.Api;
using Verifalia.Api.Security;

class MyTotpProvider : ITotpTokenProvider
{
  public Task<string> ProvideTotpTokenAsync(CancellationToken cancellationToken)
  {
    // TODO: Ask the user to provide their TOTP token

    return Task.FromResult("123456");
  }
}

var bearerAuth = new BearerAuthenticationProvider("username",
  "password",
  new MyTotpProvider())

var verifalia = new VerifaliaRestClient(bearerAuth);

// The Java SDK does not support this feature yet.

const verifalia = new VerifaliaRestClient({
  authenticator: new BearerAuthenticator('username',
    'password',
    {
      async provideTotp() {
        // TODO: Obtain the TOTP either from the user directly or from an external device
        return '123456';
      }
    })
});

// The PHP SDK does not support this feature yet.

// The Go SDK does not support this feature yet.

# The Ruby SDK does not support this feature yet.

TLS mutual authentication

Uses a cryptographic X.509 client certificate to authenticate an API consumer, through the TLS protocol. This method, also called mutual TLS authentication (mTLS) or two-way authentication, offers the highest degree of security, as only a cryptographically-derived key (and not the actual credentials) is sent over the wire on each API request.

Authenticate through a certificate
Language:

curl --cert mycertificate.pem \
    https://api-cca.verifalia.com/v2.6/...

var certificate = new X509Certificate2("mycertificate.pem");
var verifalia = new VerifaliaRestClient(certificate);

// The Java SDK uses the Java Keystore (JKS) to retrieve TSL client
// certificates. For additional information please see:
// https://github.com/verifalia/verifalia-java-sdk#authenticating-via-x509-client-certificate-tls-mutual-authentication

ClientCertificateAuthenticationProvider authProvider =
    new ClientCertificateAuthenticationProvider("mycertificate",
        "mypassword",
        new File("identity.jks"),
        new File("truststore.jks"))

VerifaliaRestClient verifalia =
    new VerifaliaRestClient(authProvider);

const verifalia = new VerifaliaRestClient({
    cert: fs.readFileSync('mycertificate.pem'),
    key: fs.readFileSync('mycertificate.key')
});

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::CERTIFICATE => '/home/gfring/Documents/pollos.pem'
]);

package main

import (
    "crypto/tls"
    "github.com/verifalia/verifalia-go-sdk/verifalia"
)

func main() {
    cert, err := tls.LoadX509KeyPair("./mycertificate.pem", "./mycertificate.key")

    if err != nil {
        panic(err)
    }

    client := verifalia.NewClientWithCertificateAuth(&cert)
	
    // TODO: Use "client" as explained below
}

verifalia = Verifalia::Client.new ssl_client_cert: './my-cert.pem',
                                  ssl_client_key: './my-cert.key'

Core concepts

Verifying email addresses

On this page:

Authentication

HTTP Basic Auth

Bearer authentication

Requesting access tokens

Using access tokens

Multi-Factor Authentication (MFA)

TLS mutual authentication

Need Help?

We're here to assist you.

Visit Our Help Center

Explore our collection of technical and non-technical articles about Verifalia's services.

Help center

Send Us a Message

Reach out to us with any questions or comments. Support is always free of charge.

Send a message

Want to chat?

Click the button below to chat live with one of our support team right now.

Online chat

Authentication

Not a developer?

Authentication

HTTP Basic Auth

Authenticate via HTTP Basic Auth
Language:

Bearer authentication

Request a bearer token
Language:

Use the obtained bearer token
Language:

Multi-Factor Authentication (MFA) v2.6+

Time-Based One-Time Password (TOTP)

Language:

TLS mutual authentication

Authenticate through a certificate
Language:

Need Help?

We're here to assist you.

Visit Our Help Center

Send Us a Message

Want to chat?

Latest tweets - twitter.com/verifalia

From our blog

Authentication

Not a developer?

Authentication

HTTP Basic Auth

Authenticate via HTTP Basic Auth Language: cURL .NET (C#) Go Java Javascript PHP Ruby

Bearer authentication

Request a bearer token Language: cURL .NET (C#) Go Java Javascript PHP Ruby

Use the obtained bearer token Language: cURL .NET (C#) Go Java Javascript PHP Ruby

Multi-Factor Authentication (MFA) v2.6+

Time-Based One-Time Password (TOTP)

Language: cURL .NET (C#) Go Java Javascript PHP Ruby

TLS mutual authentication

Authenticate through a certificate Language: cURL .NET (C#) Go Java Javascript PHP Ruby

Need Help?

We're here to assist you.

Visit Our Help Center

Send Us a Message

Want to chat?

Latest tweets - twitter.com/verifalia

From our blog

Authenticate via HTTP Basic Auth
Language:

Request a bearer token
Language:

Use the obtained bearer token
Language:

Language:

Authenticate through a certificate
Language: