API/Authentication Tutorial

Authentication Tutorial

This tutorial walks through how to log in to the **Verofy API** using **Token Authentication**.

Authentication Types

There are two authentication methods available in the Verofy API:

Token Authentication

For **user-facing clients**, such as mobile apps or user-written scripts.

• Login process takes multiple steps
• Balances security with user convenience
• Users log in with their email and password

Key Authentication

For **automated clients**, such as backend scripts or services.

• Login process is a single step
• Requires an administrator to manage keys
• Intended for systems that cannot handle interactive authentication

---

This tutorial focuses on **Token Authentication**.

---

Login using Token Auth

The Token Auth flow uses two types of tokens to maintain secure and efficient access:

• **Refresh Token**
• **Access Token**

See below for their roles and lifecycles.

---

Understanding Refresh and Access Tokens

Refresh Token

• **Long-lived**
• May be used **only once**
• Can be invalidated by the server at any time
• Used to obtain a **new Access Token**

Access Token

• **Short-lived**
• May be used **unlimited times** until it expires
• Used to authenticate the user with most endpoints
• Cannot be used to issue new tokens

Together, these provide a secure authentication mechanism that avoids transmitting raw credentials for every request.

---

Send User Credentials to the "login" Endpoint

To perform a login using Token Authentication, you will need an existing **Verofy user account**. If you do not have one, please contact your system administrator.

The login endpoint accepts a `POST` request to:

<api_url>/<version>/login

It expects the following **JSON body parameters**:

• `email`
• `password`

If the provided credentials are valid, the endpoint returns a **refresh-token**.

⚠️ **Important:** DO NOT send user credentials over plain HTTP! Always use **HTTPS**. You can use the Health Check endpoint to verify you are using a secure base URL.

---

Example: Python Login Script

import requests
import json
import getpass

# Don't hard-code or store user credentials! Always ask the user.
ident = {
    "email": getpass.getuser(),
    "password": getpass.getpass()
}

response = requests.post("https://www.example.com/v1/login", json=ident)

if response.status_code == 200:
    refresh_token = response.json()["refresh-token"]
    print("Got new refresh token:\t" + refresh_token)
else:
    print("Failed to login!")

If successful, you will receive a **refresh token** in the response.

Use this token to obtain an **access token**, which will authenticate you with most API endpoints.

---

Next: → API/Endpoint Documentation