Xink REST API Guide: OAuth, Discovery and Endpoints

Version: 1.4

Date: Jan 23, 2025

Short answer:
Use the Xink REST API with OAuth2 client credentials. First authenticate, then discover your account’s API root, and finally call the required controller endpoints with the correct scopes.

Summary: This guide explains how to authenticate against the Xink API, discover the correct data center, and use available API controllers for accounts, employees, images, signatures, rerouting, managed accounts, and shared mailboxes.

Table of Contents

• Overview
• Step 1. Authentication and authorization
• Step 2. Discovery
• Step 3. Request to an APIRoot
• Summary of all available API controllers
  • Account
  • Employee
  • Image
  • Signature
  • Signature Import
  • Rerouting
  • Managed Accounts
  • Shared Mailboxes
• Examples of API controller request and response
  • Scopes
  • Account
  • Employee
  • Image
  • Signature
  • Rerouting
  • Managed Accounts
  • Shared Mailboxes

Overview

Xink provides a REST API for external clients. All traffic between your client application and the Xink service is sent over encrypted HTTPS requests and responses.

The standard flow is:

1. Authenticate and obtain an access token
2. Discover your account’s API root
3. Call the required API endpoint using the correct scope

Step 1. Authentication and authorization

Xink uses OAuth2 to control access to the API. External clients should use the Client Credentials grant type.

Before calling the API, create an API user in the Xink admin portal:

Preferences > Admins

Add a dedicated API user with the required permissions and a strong password. In this guide, the word user refers to that API user.

To get an access token, make a POST request to the token endpoint. Send the body as application/x-www-form-urlencoded, not JSON.

Example request body:

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=employeeread%20other_necessary_scopes

All other API calls in this guide use JSON for request and response bodies unless otherwise stated. For example, file uploads use multipart/form-data.

Scopes

Scopes control access to specific API endpoints.

• employeeread (read)
• employeefieldsread (read)
• employeectrl (write)
• employeesignaturesread (read)
• signaturectrl (write)
• managedaccountsread (read)
• managedaccountsctrl (write)

Step 2. Discovery

Xink uses multiple data centers. Before calling an endpoint, discover which API root belongs to your account.

Make a GET request to:

Example response for the EU data center:

{
    "Success": true,
    "DataCenterID": "EU",
    "APIRoot": "https://e-eu.xink.io",
    "SyncRoot": "https://s-eu.xink.io",
    "ImgRoot": "https://i-eu.xink.io",
    "TrackingRoot": "https://t-eu.xink.io"
}

Step 3. Request to an APIRoot

Use the APIRoot returned by discovery when calling the API.

Example:

For example, the scopes employeeread and employeesignaturesread are required to retrieve employees and signatures. Each operation may require one or more scopes.

By default, the token is valid for 2 hours from the authorization request.

Summary of all available API controllers

Account

Employee

Image

Signature

Signature Import

Rerouting

Managed Accounts

Shared Mailboxes

Examples of API controller request and response

The examples below show sample endpoints, required scopes, and example request and response payloads for the available API controllers.

You can keep the existing example sections below as they are, since the endpoint examples and JSON payloads are already useful and well structured.