Authentication

Overview & Concepts

social.plus uses a dual authentication approach to ensure both application security and user verification:

API Key

Purpose: Identifies your application to social.plus servers
Scope: Application-level authentication
Usage: Required for SDK initialization
Security: Keep secure, never expose in client code

Auth Token

Purpose: Server-to-server verification that the user is validated by your backend
Scope: User-level authentication with your system
Usage: Optional for development, required for production
Security: Generated by your backend, proves user is legitimate

How Auth Tokens Work

Auth tokens enable server-to-server communication between social.plus and your backend:

User Authentication

Your app authenticates the user with your own authentication system (login, OAuth, etc.)

Backend Token Generation

Your backend server generates an auth token for the verified user and sends it to your app. Learn how to implement this →

social.plus Verification

When your app logs into social.plus, the auth token proves to social.plus that your backend has verified this user

Secure Communication

social.plus can now trust that this user session is legitimate and validated by your system

Why Auth Tokens? This approach ensures that only users who have been properly authenticated by your backend can access social.plus features, maintaining security and preventing unauthorized access.

When Do You Need Each?

// Production mode - API key + auth tokens
const client = Client.create({
  apiKey: 'your-prod-api-key',
  region: 'sg'
});

// Secure login with auth token from your backend
await client.login({
  userId: 'user-123',
  displayName: 'John Doe',
  authToken: 'token-generated-by-your-backend' // Proves user is verified by your system
});

Auth tokens must be generated by your secure backend after verifying the user. This ensures server-to-server trust between social.plus and your authentication system.

Quick Start (Basic Authentication)

Step 1: Initialize the SDK

Start by setting up the social.plus client with your API key:

let client = try! AmityClient(apiKey: "your-api-key", region: .SG)

Authenticate users to access social.plus features:

Task { @MainActor in
    do {
        try await client.login(
            userId: "user-123",
            displayName: "John Doe",
            authToken: "your-auth-token", // Optional for development
            sessionHandler: sessionHandler
        )
        print("Login successful")
    } catch {
        print("Login failed: \(error)")
    }
}

Step 3: Check Authentication Status

Verify if a user is currently logged in:

if (client.sessionState == .established) {
    let currentUserId = client.getCurrentUserId()
    print("Current user: \(currentUserId)")
} else {
    // Proceed to social.plus Authentication
    authenticateToSocialPlus()
}

Step 4: Logout

End the user session: For an extra layer of security, which ensures accessToken revocation prior to performing logout(). Should the SDK fail to revoke the accessToken, the SDK will not proceed to logout and will throw an exception to notify the failure.

do {
    try await client.secureLogout()
} catch {
    /// Handle error from revoking accessToken here
}

Understanding Session States

Session states indicate what’s happening with user authentication. social.plus SDK automatically manages these states according to the flow shown in the diagram below:

notLoggedIn

Ready for login - user needs to authenticate
Entry points: App start (no session), logout, login failure

establishing

Login in progress - authentication being processed
Entry point: When login() is called from notLoggedIn state

established

Fully authenticated - SDK ready, all features available
Entry points: Successful login, successful token renewal

tokenExpired

Token renewal needed - automatic renewal attempted
Entry point: When auth token expires during established state

terminated

Session forcibly ended - user banned or deleted
Entry points: User banned/deleted from established or tokenExpired states

Session Flow

Understanding the complete session state flow helps you build responsive apps:

SDK Initialization

App starts: Always begins in the start state, then immediately moves to:

No saved session: Moves to notLoggedIn state
Has saved session: Moves to established state (if session valid)

User attempts login:

notLoggedIn → establishing (login in progress)
Login succeeds: establishing → established
Login fails: establishing → notLoggedIn

Active Session Management

During active use in established state:

Token expires: established → tokenExpired
Token renewed successfully: tokenExpired → established
User banned/deleted: established → terminated
Manual logout: established → notLoggedIn

Token Expiration Handling

When in tokenExpired state:

Auto-renewal succeeds: Returns to established state
Auto-renewal fails: User may need to re-authenticate
User banned during renewal: Moves to terminated state
Manual logout: Moves to notLoggedIn state

Session Termination

From terminated state:

Only way out is through logout → notLoggedIn
User must re-authenticate to access features again

Observing Session State

Monitor session state changes to handle authentication in your app:

var cancellable: AnyCancellable?
// Observe session state changes
cancellable = client.$sessionState.sink { sessionState in
    switch sessionState {
    case .notLoggedIn:
        // Show login screen
        self?.showLogin()
    case .establishing:
        // Show loading indicator
        self?.showLoading()
    case .established:
        // Hide loading indicator, proceed to app
        self?.hideLoading()
        self?.proceedToApp()
    case .tokenExpired:
        // Attempt to refresh token (Optional)
        self?.showTokenRefreshIndicator()
    case .terminated:
        // Handle session termination
        self?.handleTermination()
    }
}

Advanced Session Management

For production apps, you’ll need sophisticated session handling with automatic token refresh:

Session Handlers for Token Refresh

Session handlers automatically manage token lifecycle:

class ProductionSessionHandler: AmitySessionHandler {
    func sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        // Call your backend to get a fresh token
        AuthService.shared.refreshToken { result in
            switch result {
            case .success(let newToken):
                renewal.renewWithAuthToken(withAuthToken: newToken)
            case .failure(let error):
                print("Token refresh failed: \(error)")
                renewal.unableToRetrieveAuthToken()
            }
        }
    }
}

// Use during login
let sessionHandler = ProductionSessionHandler()
try await client.login(
    userId: userId,
    displayName: displayName,
    authToken: authToken,
    sessionHandler: sessionHandler
)

Security Best Practices

Production Token Management

Backend Token Generation

Auth tokens must be generated by your secure backend to establish server-to-server trust with social.plus.View API Reference →

// Example Node.js backend - generates tokens for verified users
app.post('/api/auth/social-plus-token', async (req, res) => {
  const { userId } = req.body;
  
  // STEP 1: Verify user is authenticated in YOUR system
  const user = await verifyUserInYourSystem(userId);
  if (!user) {
    return res.status(401).json({ error: 'User not authenticated in your system' });
  }
  
  // STEP 2: Generate social.plus auth token for this verified user
  const authToken = generateSocialPlusToken(userId);
  
  // STEP 3: Return token to your app for social.plus login
  res.json({ 
    authToken,
    message: 'Token generated for verified user'
  });
});

Why this approach?

Your backend vouches for the user’s authenticity to social.plus
social.plus trusts users who have valid tokens from your verified backend
Prevents unauthorized access to social.plus features
Maintains security boundary between your auth system and social.plus

Authentication Best Practices

Do's ✅

Don'ts ❌

Troubleshooting

Session state stuck in 'establishing'

Frequent token expiration

Session handler not called

App crashes on session state change

Next Steps

User Management

Learn about user profiles and management

Social Features

Start building social features

Chat Features

Add real-time messaging

Security Settings

Configure security in the Console

Powered by

Getting Started

Fundamentals

Social

Chat

Overview & Concepts

API Key

Auth Token

How Auth Tokens Work

When Do You Need Each?

Quick Start (Basic Authentication)

Step 1: Initialize the SDK

Step 3: Check Authentication Status

Step 4: Logout

Understanding Session States

notLoggedIn

establishing

established

tokenExpired

terminated

Session Flow

Observing Session State

Advanced Session Management

Session Handlers for Token Refresh

Security Best Practices

Production Token Management

Authentication Best Practices

Troubleshooting

Next Steps

User Management

Social Features

Chat Features

Security Settings

Powered by

Getting Started

Fundamentals

Social

Chat

​Overview & Concepts

​Authentication in social.plus

API Key

Auth Token

​How Auth Tokens Work

​When Do You Need Each?

​Quick Start (Basic Authentication)

​Step 1: Initialize the SDK

​Step 2: Login User

​Step 3: Check Authentication Status

​Step 4: Logout

​Understanding Session States

notLoggedIn

establishing

established

tokenExpired

terminated

​Session Flow

​Observing Session State

​Advanced Session Management

​Session Handlers for Token Refresh

​Security Best Practices

​Production Token Management

​Authentication Best Practices

​Troubleshooting

​Next Steps

User Management

Social Features

Chat Features

Security Settings

Overview & Concepts

Authentication in social.plus

How Auth Tokens Work

When Do You Need Each?

Quick Start (Basic Authentication)

Step 1: Initialize the SDK

Step 2: Login User

Step 3: Check Authentication Status

Step 4: Logout

Understanding Session States

Session Flow

Observing Session State

Advanced Session Management

Session Handlers for Token Refresh

Security Best Practices

Production Token Management

Authentication Best Practices

Troubleshooting

Next Steps