External Login via API

The External Login API enables external applications to authenticate with R-COM Gateway and obtain access tokens for calling protected API endpoints. This guide covers the complete authentication flow — from initial login to token refresh — so you can integrate your systems securely and reliably.

---

How It Works

Token-based authentication follows a straightforward flow:

1. Your application sends credentials to the login endpoint and receives a Token and RefreshToken.
2. The Token is included in the Authorization header of every subsequent API request.
3. When the token expires, your application calls the refresh endpoint to obtain a new token — without resending user credentials.

---

Prerequisites

Before you begin, make sure you have the following:

Requirement	Description
Username	A valid user account registered on the platform.
Password	The password associated with the user account.
ClientID	A GUID that identifies the client (tenant) your application belongs to. Obtain this from your administrator.

---

Step 1: Authenticate with the Login Endpoint

Send a POST request to the external login endpoint with your credentials.

Request

1POST /api/users/external-login
2Content-Type: application/json

Request Body

1{
2"Username": "your_username",
3"Password": "your_password",
4"ClientID": "00000000-0000-0000-0000-000000000000"
5}

Field	Type	Description
Username	string	Your registered username or email address.
Password	string	The account password.
ClientID	string (GUID)	The unique identifier for your client/tenant.

Success Response

On successful authentication, the API returns user details along with the token:

1{
2"UserID": "25409875-6080-492c-8433-7f664eac9932",
3"UserName": "admin@example.com",
4"Status": true,
5"ClientStatus": true,
6"ClientID": "ee9f73b3-474e-4d10-884a-04196d47dabf",
7"ClientName": "My Organization",
8"IsSuperAdmin": false,
9"Groups": [ "..." ],
10"Roles": [ "..." ],
11"Token": "<access_token>",
12"Last_Login_Time": null,
13"External_UID": null,
14"InactiveTimeOutInMinutes": 10,
15"TokenExpiry": "2026-03-17T07:59:34.4121026Z"
16}

Response Fields

Field	Description
UserID	The unique identifier of the authenticated user.
UserName	The username or email used to log in.
Status	Indicates whether the user account is active.
ClientStatus	Indicates whether the client/tenant is active.
ClientID	The identifier of the client the user belongs to.
ClientName	The display name of the client/tenant.
IsSuperAdmin	Whether the user has super-admin privileges.
Groups	List of groups the user is assigned to.
Roles	List of roles the user holds.
Token	The access token to use for authenticated API calls.
InactiveTimeOutInMinutes	Session inactivity timeout in minutes.
TokenExpiry	The UTC timestamp when the token expires.

tip

Store the Token, RefreshToken, and TokenExpiry values securely. You will need them for subsequent API calls and token renewal.

---

Step 2: Call Protected APIs

Once you have a valid token, include it in the Authorization header of every request to a protected endpoint.

1GET /api/your-protected-endpoint
2Authorization: Bearer <Token>

The platform validates the token on each request. If the token is valid and has not expired, the API processes the request normally.

---

Step 3: Handle Token Expiry

Tokens have a limited lifetime (indicated by the TokenExpiry field). When a token expires, the API responds with:

1HTTP/1.1 401 Unauthorized

When you receive a 401 response, do not resend user credentials. Instead, use the refresh token flow described below.

warning

Do not hard-code token lifetimes in your application. Always check the TokenExpiry value returned by the API and implement proactive or reactive refresh logic.

---

Step 4: Refresh an Expired Token

Call the refresh endpoint with your current token and refresh token to obtain a new token pair.

Request

1POST /api/users/refresh-token-external
2Content-Type: application/json

Request Body

1{
2"Token": "<current_token>",
3"RefreshToken": "<refresh_token>"
4}

Field	Type	Description
Token	string	The expired (or still-valid) access token.
RefreshToken	string	The refresh token received during login or a previous refresh.

Success Response

1{
2"Token": "<new_token>",
3"RefreshToken": "<new_refresh_token>",
4"TokenExpiry": "2026-03-17T09:30:00Z"
5}

After a successful refresh:

1. Replace your stored Token, RefreshToken, and TokenExpiry with the new values.
2. Retry the failed API request using the new token.

caution

Always discard old token values after a refresh. Reusing expired or rotated tokens will result in authentication failures.

---

C# Integration Example

Below is a complete C# example demonstrating the login and token-refresh flow.

Data Models

1public class ExternalLoginRequest
2{
3  public string Username { get; set; } = "";
4  public string Password { get; set; } = "";
5  public string ClientID { get; set; } = "";
6}
7
8public class RefreshTokenRequest
9{
10  public string Token { get; set; } = "";
11  public string RefreshToken { get; set; } = "";
12}

Login and Use Token

1var loginResponse = await httpClient.PostAsJsonAsync(
2  "/api/users/external-login",
3  new ExternalLoginRequest
4  {
5      Username = "your_username",
6      Password = "your_password",
7      ClientID = "00000000-0000-0000-0000-000000000000"
8  });
9
10var loginResult = await loginResponse.Content.ReadFromJsonAsync<JsonElement>();
11var token = loginResult.GetProperty("Token").GetString();
12
13httpClient.DefaultRequestHeaders.Authorization =
14  new AuthenticationHeaderValue("Bearer", token);

Refresh an Expired Token

1var refreshResponse = await httpClient.PostAsJsonAsync(
2  "/api/users/refresh-token-external",
3  new RefreshTokenRequest
4  {
5      Token = token ?? string.Empty,
6      RefreshToken = "<refresh_token>"
7  });

---

Best Practices

• Use exact field names — The API returns Token (capital T), not token or access_token. Match the casing exactly when reading response properties.
• Refresh proactively — Rather than waiting for a 401, compare the current time against TokenExpiry and refresh the token before it expires.
• Store tokens securely — Never log or expose tokens in client-side code, URLs, or version control. Use secure storage mechanisms appropriate for your platform.
• Handle multiple groups and roles — The Groups and Roles arrays may contain multiple entries depending on the user's configuration. Design your authorization logic accordingly.
• Always replace old tokens — After a successful refresh, discard the previous Token and RefreshToken and use only the newly returned values.