API Getting Started

LoginRadius Authentication APIs are RESTful services that help developers integrate secure login, registration, and identity verification features into their applications. These APIs cover everything from traditional email/password logins to advanced options like multi-factor authentication (MFA), passwordless login, and social sign-ins.

They remove the complexity of building authentication from scratch by providing reliable, scalable, and secure identity management out of the box.

Retrieve LoginRadius API Key and Api Secret

• Log in to the Admin Console.
• Navigate to Tenant Settings and locate the API Configuration section. You will find the API Key and secret required for API endpoints. For more information, refer to the API Configuration document.

Retrieve SOTT

SOTT (Secure One-Time Token) is a time-bound token used in the LoginRadius Authentication API for secure user registration. It adds an extra layer of protection—especially effective against bots—on both web and mobile platforms.

Usage of SOTT

• Mobile: Acts as an alternative to CAPTCHA, which can be challenging on smaller screens.
• Web: Used alongside CAPTCHA or as a standalone security measure.

Token Expiry: By default, automatically generated SOTTs expire after 10 minutes. Custom expiration is possible via the Admin Console, Management SOTT API, or manual generation methods.

Ways to Generate SOTT

• Manually
  Generate using your API Key, API Secret, and timestamp. Refer to language-specific logic or use the Management SOTT API.

• Via SDK
  The SDK automatically generates and manages SOTT during user registration API calls—no manual setup is required. For more information, refer to the SOTT documentation.

LoginRadius API Playground

The LoginRadius API Playground offers an easy way to test and understand how APIs work. Here’s how you can run API requests using your API credentials.

Prerequisites
Before running an API, ensure you have:

• Your API Key and API Secret from the Admin Console(As described earlier in this document)
• The API endpoint you want to test (e.g., https://api.loginradius.com/identity/v2/manage/account/identities)
• All required parameters for the specific endpoint (e.g., email, UID or access token, etc. )

Steps to Use the API Playground

1. Visit the LoginRadius API Docs

   • Go to: https://www.loginradius.com/docs
   • Navigate to the API you want to test from the sidebar under APIs section

2. Select the Endpoint
   Example:
   GET /identity/v2/manage/account/identities
   Retrieves all identities linked to a specified email.

3. Fill in the Parameters

   • API Key and/or API Secret
   • Email or UID
   • Other fields based on the selected endpoint

4. Send the Request
   Click the Send API Request button.
   The response will appear below in the response section.

Sample cURL Request:

 curl \-X GET "https://api.loginradius.com/identity/v2/manage/account/identities?apikey=YOUR\_API\_KEY\&apisecret=YOUR\_API\_SECRET\&[email protected]" \\ \-H "Accept: application/json"

Replace YOUR_API_KEY, YOUR_API_SECRET, and [email protected] with actual values.

Common Use Cases for LoginRadius APIs

Use Case	Description
User Login & Registration	Register and authenticate users using email/password, phone number, or social accounts.
Multi-Factor Authentication (MFA)	You can add a second layer of security via OTPs (email/SMS), authenticator apps, or various other methods.
Single Sign-On (SSO)	Allow users to access multiple apps with one login session.
Passwordless Login	Enable logins through email or SMS-based one-time links or codes.
Social Login Integration	Support 20+ providers like Google, Facebook, Twitter, and LinkedIn.
Progressive Profiling	Collect user information gradually over multiple interactions.
User Session Management	Manage user sessions securely with access tokens, refresh tokens, and logout APIs.
Account Recovery	Secure workflows for forgot passwords, account unlock, and reset passwords.
Custom Workflows	Use webhooks, custom fields, and rules to tailor the authentication process.

LoginRadius Authentication APIs are designed to be flexible, developer-friendly, and secure—making them ideal for any modern application that manages user identities.

API Security

This section explains how to access different types of LoginRadius API endpoints securely.

Credential-Based Authentication

For backend/admin APIs (e.g., Account, Roles Management, Custom Object), you can authenticate using:

• Headers:
  X-LoginRadius-ApiKey and X-LoginRadius-ApiSecret
• Query String:
  Append apikey and apisecret to the API URL
  Example:
  https://api.loginradius.com/.../account?apikey=API_KEY&apisecret=API_SECRET

Access Token-Based Authentication

Used for APIs involving user sessions. You can pass the access token in one of the following ways:

• Header (recommended):
  Authorization: Bearer <ACCESS_TOKEN>
  Best for secure, server-side requests.

• Query String:
  ...?access_token=<ACCESS_TOKEN>&apikey=<API_KEY>
  Useful for testing or simple integrations.

• Request Body (for POST/PUT):

{ "access_token": "<ACCESS_TOKEN>" }

Used when the token needs to be part of the payload.

Recommended Secure Practice

Parameter	Recommended Location	Notes
API Key	Query or Header	It’s OK to pass in the query string for most use cases.
API Secret	Header only (secure)	Never expose in client-side or public URLs.
Access Token	Header (preferred)	Use Authorization: Bearer <token> for the most secure flow.
UID	Query or Path	Safe for identifying resources, e.g., /user?uid=abc123.

API Request Signing (Optional Advanced Security)

API Request Signing is an advanced authentication method that replaces sending the raw API Secret with a time-sensitive, hashed signature for better security.

Use Request Signing when:

• You want to avoid exposing your API Secret directly in requests.
• You need extra protection for sensitive backend operations (like managing accounts, roles, etc.).
• You want to verify payload integrity and prevent replay attacks by setting a request expiry.

Note: This feature must be enabled on your LoginRadius account. Please contact LoginRadius Support to activate it.

How It Works

Instead of sending the API Secret, you send a hash (HMAC-SHA256) created from:

• The request expiry time
• The API endpoint (URL)
• The payload (if any)
• Using your API Secret as the signing key

LoginRadius will validate the hash and ensure the request has not been tampered with or reused.

Step-by-Step Implementation

Set the Request Expiry Time

Include a header that defines when the request should expire (in UTC):

• Eg: X-Request-Expires : 2018-4-18 6:15:10 PM (yyyy-M-d h:m:s tt) // UTC
• If this value exceeds the current UTC datetime, API will return an error message.

Create the Encoded URL

To create the hash, the URL must be encoded; see below for the steps.

A. Build the full URL: Join the API endpoint and query string parameters (make sure parameter values are URL-encoded).

https://api.loginradius.com/identity/v2/manage/account?apikey=\{API\_KEY\}\&param=value

B. Decode this full URL: Decode it completely.

C. Re-encode the decoded URL: This re-encoded version will be used in the next step.

Construct the Signing String

signingString \= X-Request-Expires \+ ":" \+ Encoded\_URL \+ ":" \+ JSON\_Payload

• If it’s a GET request, leave JSON_Payload empty.
• Use an empty string ("") if there is no payload.
• Use your API Secret to sign the Hash: hashBytes= HMACSHA256(signingString) //Use your API Secret as the key here.
• Get the Hash value by converting hashBytes into a base64 string.

Add the Hash to the Request Header

Pass the generated hash using the Digest header:

Digest: SHA-256=\<hash\_value\>

Example Headers Summary

Content-Type: application/json  
X-LoginRadius-ApiKey: <YOUR_API_KEY>  
X-Request-Expires: 2025-03-20 18:30:00  
Digest: SHA-256: <GENERATED_HASH>

Request Signing Modes

LoginRadius supports two signing validation modes:

Mode	Description
Strict	Requests must include a valid hash.
Preferred	It is validated if the hash is present; otherwise, it falls back to API Secret.

Extended Features

Unlock powerful enhancements that go beyond basic authentication. This section covers advanced capabilities in the LoginRadius APIs to help you build more secure, flexible, and optimized applications.

Null Value Support

LoginRadius lets you explicitly set fields to null, ideal for profile cleanup and precise data control.

To enable the Null Support:

Pass nullsupport=true as a query parameter in your POST or UPDATE API call.

POST /identity/v2/auth/account?nullsupport=true

Example Payload:

{"FirstName": null}

By default, nullsupport is false.

Supported Fields

Includes: UserName, Prefix, FirstName, MiddleName, LastName, Suffix, NickName, ProfileName, BirthDate, Gender, Website, ThumbnailImageUrl, ImageUrl, Favicon, ProfileUrl, HomeTown, State, City, Industry, About, TimeZone, LocalLanguage, CoverPhoto, TagLine , Language, MainAddress, LocalCity, ProfileCity, LocalCountry, RelationshipStatus, Religion, Political, HttpsImageUrl, IsGeoEnabled, Associations, Honors, PublicRepository, RepositoryUrl, ProfessionalHeadline, Currency, StarredUrl, GistsUrl, Company, GravatarImageUrl, Languages , PlacesLived , Addresses , PhoneNumbers and Custom Fields.

Note: UserName can only be set to null via the LoginRadius Management API.

Removing JSON Objects from Array Fields

To remove an entry from array-based fields, use the operation flag "op": "delete".

Supported Fields

• Languages
• PlacesLived
• Addresses
• PhoneNumbers

Example:

{"Languages": [{"Name": "Hindi", "Proficiency": "Expert", "op": "delete"} ]}

Server-Side Validation

Your custom validation rules (configured in the LoginRadius Admin Console) are enforced during API calls.

Sample Error Response:

{
  "ErrorCode": 1134,
  "Message": "Validation failed for one or more fields.",
  "Errors": [
    { "FieldName": "city", "ErrorMessage": "The City field is required." },
    { "FieldName": "password", "ErrorMessage": "Password must be at least 6 characters." } ]}

Contact LoginRadius Support to enable this feature.

Password Compliance Check

Use the IsSecurePassword field to verify if a user's password meets your current policy.

When Is It Useful?

If you've updated your password policy and want to identify non-compliant users.

Response Example:

{ "IsSecurePassword": false}

Prompt users to reset passwords if false. Contact LoginRadius Support to enable this feature.

Filter API responses using the fields query parameter to return only the needed data.

Syntax Rules:

• Multiple fields: fields=FirstName, LastName
• Nested fields: fields=Identities(Email/Value)
• Wildcard: fields=*

It improves the performance and reduces the bandwidth.

Enhance Analytics with Custom Headers

Improve tracking accuracy by forwarding client environment data via headers:

Header	Purpose
X-Origin-IP	Client's IP address
X-Origin-User-Agent	User-agent string
X-Origin-Host	Client host (absolute URL)
X-Origin-Accept-Language	User's preferred language
X-Platform	Client platform info

Referer Header for Registration Source

Automatically set the Registration Source using the Referer header.

Example:

Source	Profile Value
Android SDK	Android
iOS SDK	iOS
Identity Experience Framework	Page URL
API/Postman/Admin Console	API

Update source by passing Referer in the header of registration API calls.

Using LoginRadius API with a Proxy

To make API requests via a proxy:

• Configure proxy settings in your SDK/web requests.
• Modify SDK’s HTTP layer if needed.

For any assistance, reach out to LoginRadius Support.

Best Practices

Practice	Description
Keep Secrets Secure	Never expose your API Secret on the client side.
Test with Real Data	Use test accounts or emails you control.
Use HTTPS	Always use the secure https protocol.
Handle Errors Properly	Check HTTP response codes and handle errors gracefully.
Rate Limits	Stay within the rate limits defined in your plan.
Use the Schema	Refer to the schema and example tabs in the playground for parameter info.

Related Resources

• Authentication API Overview
• API Configuration Overview
• API response Code