Authentication Methods

Authentication Methods in Okto via API

Authentication in Okto serves as the foundation for secure user interactions within your application. Okto provides multiple authentication methods to suit different use cases and user preferences, each with its own strengths and implementation approach.

By implementing one or more of these authentication methods, you can provide your users with a secure, seamless experience while leveraging Okto's powerful blockchain capabilities.

Choosing Your Authentication Method

Okto offers flexible authentication options to fit your application's needs. They can be broadly categorized into two types: Single-Step Social & JWT Flows and Multi-Step OTP Flows.

Single-Step: Social & JWT Authentication

These methods involve a single call to the Okto authenticate endpoint, where you exchange a token from an external provider (like Google or your own system) for an Okto authToken.

• Google Authentication
• Apple Authentication
• X (Twitter) Authentication

Multi-Step: OTP-Based Authentication

These methods provide a secure sign-in flow using a one-time password (OTP) sent to the user's device. The process involves three distinct API calls: Send OTP, Verify OTP, and finally, Authenticate.

• Email OTP Authentication
• WhatsApp OTP Authentication

Authentication Flow Architecture

All authentication methods in Okto follow a similar high-level architecture:

1. User Identity Verification - Validate user identity through Google, WhatsApp, or Email
2. Session Key Generation - Create ephemeral cryptographic keys for the session
3. Session Establishment - Generate secure session keys for ongoing interactions
4. User Wallet Creation - Automatically create blockchain wallets for new users
5. Authorization Token Generation - Create an Okto Auth Token for API requests

This architecture ensures secure, seamless authentication while maintaining the self-custodial nature of user wallets.

The Okto Auth Token

The ultimate output of every authentication flow is an Okto Auth Token. This is a short-lived, session-specific token that proves your application has the user's permission to perform actions.

The authToken must be included in the Authorization header as a Bearer token for all subsequent API calls.

Universal Implementation Guide

All authentication methods converge on a single, powerful endpoint: POST /api/oc/v1/authenticate. While the initial steps differ, the final call to this endpoint follows a universal pattern. Understanding this flow is key to implementing any method.

Here are the universal steps your backend must perform:

Step 1: Obtain an idToken

This is the initial credential that proves the user's identity. Where you get it depends on the method:

• Social Logins (Google, Apple, Twitter): You receive an idToken (or access token) directly from the provider's OAuth flow after the user signs in.
• Custom JWT: You generate a JWT for your user from your own authentication system.
• OTP Flows (Email, WhatsApp): You complete the send and verify steps to receive a temporary auth_token, which serves as the idToken for this flow.

Step 2: Generate a New Session Key

For each new login session, you must generate a new, unique cryptographic key pair. This key pair represents the user's session and is used to sign subsequent requests.

The session key is securely associated with the user's wallet on-chain, enabling secure, signless transactions. It is distinct from your client keys and the user's login credentials.

You can use our Template SessionKey utility to generate these keys easily.

Step 3: Construct the authenticate Payload

This is the most critical step. You will construct a detailed JSON object to send to the authenticate endpoint. It consists of two main parts: authData and sessionData, along with their corresponding signatures.

{
  "authData": {
    "idToken": "...", // The token from Step 1
    "provider": "..." // e.g., 'google', 'apple', 'client_jwt', 'okto'
  },
  "sessionData": {
    "nonce": "...", // A unique UUID for this request
    "clientSWA": "...", // Your client's smart wallet address
    "sessionPk": "...", // The public key from the session key generated in Step 2
    "maxPriorityFeePerGas": "...",
    "maxFeePerGas": "...",
    "paymaster": "...",
    "paymasterData": "..."
  },
  "sessionPkClientSignature": "...", // Signature of the session public key, signed by your client private key
  "sessionDataUserSignature": "..." // Signature of the session public key, signed by the new session private key
}

Step 4: Call the authenticate Endpoint

Send the complete payload from Step 3 to POST /api/oc/v1/authenticate.

Step 5: Handle the Response & Generate the Final Okto Auth Token

A successful response will contain the userSWA (the user's smart wallet address) and session details:

{
  "status": "success",
  "data": {
    "userSWA": "0x8B20023FC47D8F8BDB7418722dBB0e3e9964a906",
    "nonce": "0x00000000000000000000000000000000f9d4db5746824690b2efeae9f9945858",
    "clientSWA": "0xe8201E368557508bF183D4e2DcE1b1A1E0bd20FA",
    "sessionExpiry": 1747481250
  }
}

Now complete your session configuration and generate the final Okto Auth Token. Our template scripts show exactly how this is done.

Store Session Data Securely: Save the sessionConfig object safely. You'll need it to regenerate the auth token or perform delegated actions later.

Verifying a Session

You can check if a stored session is still valid by calling the /api/oc/v1/verify-session endpoint with a generated Okto Auth Token. This is useful to determine if a user needs to log in again.

For complete implementation examples, refer to the Okto TS SDK Template Repository which contains working code samples for all authentication methods.