Authentication

You will need to authenticate your requests to access any of the endpoints in the Tether API. In this guide, we will look at how authentication works. Tether uses JWT (JSON Web Token) authentication for secure API access.

Obtaining a JWT token

To authenticate with the Tether API, you first need to obtain a JWT token by logging in with your credentials. Send a POST request to the /api/auth/login endpoint:

Request body

Name
email
Type
string
Description
Your account email address.
Name
password
Type
string
Description
Your account password.

Login Request

POST

/api/auth/login

curl -X POST https://your-tether-instance.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "fullName": "John Doe",
    "organizationId": "507f1f77bcf86cd799439012",
    "accessRole": "ADMIN"
  }
}

Using the JWT token

Once you have obtained a token, include it in the Authorization header of all subsequent requests using the Bearer scheme:

Example authenticated request

curl https://your-tether-instance.com/api/contacts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Keep your JWT token secure and never expose it in client-side code or public repositories. Tokens have an expiration time and will need to be refreshed periodically.

Verifying a token

You can verify if a token is still valid using the verify endpoint:

This endpoint checks if your current token is valid and returns a confirmation message.

Request

GET

/api/auth/verify-token

curl https://your-tether-instance.com/api/auth/verify-token \
  -H "Authorization: Bearer {token}"

Success Response (200)

{
  "message": "Token is good"
}

Error Response (401)

{
  "error": "Invalid or expired token"
}

User registration

New users can be registered through the registration endpoint. Note that this may require admin privileges depending on your organization settings.

Required attributes

Name
email
Type
string
Description
Email address for the new user.
Name
password
Type
string
Description
Password for the new user.
Name
firstName
Type
string
Description
First name of the user.
Name
lastName
Type
string
Description
Last name of the user.

Optional attributes

Name
organizationId
Type
string
Description
Organization to assign the user to.
Name
role
Type
string
Description
User role (SUPERADMIN, ADMIN, DEPARTMENT_HEAD, SALES_REP).

Request

POST

/api/auth/register

curl -X POST https://your-tether-instance.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password",
    "firstName": "Jane",
    "lastName": "Smith"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439013",
    "email": "newuser@example.com",
    "fullName": "Jane Smith",
    "organizationId": "507f1f77bcf86cd799439014",
    "accessRole": "SALES_REP"
  }
}

User roles

Tether uses a role-based access control system with the following hierarchy (highest to lowest):

Role	Description
`SUPERADMIN`	Platform administrator with full access to all organizations
`ADMIN`	Organization administrator with full access within their organization
`DEPARTMENT_HEAD`	Department manager with access to department resources
`SALES_REP`	Individual user with access to assigned contacts and conversations

Token expiration

JWT tokens have an expiration time. When a token expires, you will receive a 401 Unauthorized response. To continue making requests, you will need to obtain a new token by logging in again.

Expired token response

{
  "error": "Token expired",
  "message": "Your session has expired. Please log in again."
}

Best practice is to implement token refresh logic in your application to handle expiration gracefully without disrupting the user experience.