# AuthenticationService

The Xero Authentication service enables authentication with Xero accounts for Xero applications. This service facilitates multi-tenant environments, securely stores authentication credentials, and manages token lifecycle. It also provides API endpoint access functions with integrated authentication handling.

## Overview

The service performs the following key functions:

* Facilitates authentication for new tenants/users
* Securely stores tenant authentication data (tokens, refresh tokens, and connection metadata)
* Handles authentication requests
* Automatically manages token lifecycle including refreshing expired tokens

## Requirements

### Prerequisites

* Registered [Xero](https://www.xero.com/za/signup/api/) account
* Application created in Xero's [developer portal](https://developer.xero.com/)
* Pre-existing database to store tenant and token information

## Authentication Flow

The following diagram illustrates the Linx-to-Xero authentication process:

<figure><img src="https://3338214469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1nxDeDH8GVCXb0XelqGm%2Fuploads%2Fgit-blob-775a91705b13454d9af1047394db064da213b143%2Fxeroauthdiagram.png?alt=media" alt="Diagram for Xero Authentication"><figcaption></figcaption></figure>

## Service Configuration

The service requires the following configuration parameters:

| Parameter             | Description                                                                                                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization URI** | The service endpoint handling authorization. The service listens for incoming requests at `[authorization-uri]/authorize`. Configure your Xero App's Redirect URI to `[authorization-uri]/callback`.                                               |
| **Redirect URI**      | The endpoint where users are redirected after successful authorization, typically a confirmation page.                                                                                                                                             |
| **Client ID**         | The application identifier from your Xero App configuration.                                                                                                                                                                                       |
| **Client Secret**     | The secure application key from your Xero App configuration.                                                                                                                                                                                       |
| **Scope**             | Defines the access permissions for the service. "openid", "profile", and "offline\_access" scopes are automatically included. For all available scopes, see: [Xero OAuth2 Scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/). |

### Database Connection

Specifies the database for storing access and refresh tokens:

The service supports four database connection options:

* **SQL Server**: Microsoft SQL Server database storage
* **SQLite**: SQLite database storage
* **PostgreSQL**: PostgreSQL database storage
* **Memory**: In-memory storage (data persists only until service restart)

> **Note**: Database must exist prior to service initialization. The service creates necessary database objects automatically. Required permissions include Create, Read, Update, and Write access.

| Parameter             | Description                                                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection String** | Database connection string for token storage. A dedicated schema (`[linx_jobscheduler]`) is created for required tables. Not required when using memory storage. |

## Authorization Process

When the service is running (in debug mode or on a Linx server), the Authorization URL becomes accessible. This directs users to a Xero authentication screen where they must log in with their credentials.

<figure><img src="https://3338214469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1nxDeDH8GVCXb0XelqGm%2Fuploads%2Fgit-blob-ef5535c43d8b1134bf5d3e64ef8240c73fb5c3ce%2Fxerologin.png?alt=media" alt="Xero User Login Screen"><figcaption><p>Xero User Login Screen</p></figcaption></figure>

<figure><img src="https://3338214469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1nxDeDH8GVCXb0XelqGm%2Fuploads%2Fgit-blob-13f67cf1218326aeb34557be466bc8f0ff25db06%2Fxeroauth.png?alt=media" alt="Xero Company Authentication Authorization"><figcaption><p>Xero Company Authentication Authorization</p></figcaption></figure>

After authentication, users select the organization (tenant) they wish to authorize and complete the authorization process.

Upon completion, users are redirected to the configured Redirect URI. This endpoint receives a `xeroUserId` query parameter that must be captured and stored alongside user profile information (this profile data is not managed by Linx). The service only stores TenantID and token-related data; the `xeroUserId` serves as the reference identifier for future operations.

<figure><img src="https://3338214469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1nxDeDH8GVCXb0XelqGm%2Fuploads%2Fgit-blob-13ec0059306974ee17937ac1dcc5adb609c2724e%2Fcallbackuri.png?alt=media" alt="Callback URI with the Xero UserID"><figcaption></figcaption></figure>

> **Important**: The `xeroUserId` must be persisted in your application as it is required for all subsequent operations, including API calls and tenant listing.

All authentication data is stored in the configured database. The table structure is managed by Linx and should not be directly accessed by external applications as the schema may change in future updates.

## Service Functions

The service provides the following functions that can be used in your Linx funcions:

### GetTenants

Returns all tenants (organizations) associated with the specified Xero user.

Parameter:

| Parameter        | Description                       |
| ---------------- | --------------------------------- |
| **Xero User ID** | The authenticated user's Xero ID. |

### CallXeroAPI

Provides generic access to Xero API endpoints with integrated authentication handling. Specify the endpoint, and the service manages authentication using the provided credentials.

Parameters:

| Parameter        | Description                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Xero User ID** | The authenticated user's Xero ID, obtained during initial authentication. This must be stored with client data as business information                                 |
| **Tenant ID**    | The organization ID for the operation. Can be retrieved using the GetTenants function, which returns all tenants associated with the specified user.                   |
| **Method**       | HTTP method for the request (supported methods: GET, POST, PUT, DELETE).                                                                                               |
| **URL**          | The Xero API endpoint to call. Example: `https://api.xero.com/api.xro/2.0/Reports/BalanceSheet` for a balance sheet report. Endpoint must be within authorized scopes. |
| **Query String** | Query parameters as required by the endpoint. Consult Xero API documentation for endpoint-specific requirements.                                                       |
| **Body**         | Request body data as required by the endpoint. Consult Xero API documentation for endpoint-specific requirements.                                                      |

> **Note**: For a complete reference of available endpoints, see: [Xero API Endpoint Documentation](https://developer.xero.com/documentation/api/accounting/overview)

The following diagram illustrates the API call flow:

<figure><img src="https://3338214469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1nxDeDH8GVCXb0XelqGm%2Fuploads%2Fgit-blob-49008c550cdd21e87bb7ee61c826872695191a27%2Fxeroapicalls.png?alt=media" alt="Diagram for Xero API calls"><figcaption></figcaption></figure>

## Links

* [Xero API Endpoint Documentation](https://developer.xero.com/documentation/api/accounting/overview)
* [Xero Authentication Setup](https://sqlformat.darold.net/)
* [Xero Scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/)