OAuth Integration

Deva uses OAuth 2.0 with OpenID Connect (OIDC) for secure user authentication. The SDK implements the Authorization Code Flow with PKCE (Proof Key for Code Exchange), which is designed for client-side applications.

How OAuth Works in Deva SDK

The SDK handles the entire OAuth flow automatically. When a user clicks login:

  1. Authorization Request - SDK generates a code challenge and redirects to Deva's login page

  2. User Authentication - User logs in and grants permissions

  3. Authorization Code - Deva redirects back with an authorization code

  4. Token Exchange - SDK exchanges the code for access tokens

  5. API Access - SDK uses the access token to fetch user data and make API calls

  6. Token Refresh - SDK automatically refreshes expired tokens in the background

PKCE Flow (No Client Secret Required)

The SDK uses PKCE instead of client secrets, making it safe for browser-based applications:

  • Code Verifier: Random string generated by the SDK

  • Code Challenge: SHA-256 hash of the code verifier

  • No Secrets: Client secret is not needed or exposed in the browser

This prevents authorization code interception attacks in public clients.

OpenID Configuration

Deva's OpenID configuration provides all OAuth endpoints and supported features:

Configuration URL:

https://www.deva.me/.well-known/openid-configuration

Key Endpoints:

  • authorization_endpoint - Where users log in

  • token_endpoint - Where codes are exchanged for tokens

  • userinfo_endpoint - Where user data is fetched

  • revocation_endpoint - Where tokens are revoked (logout)

Authorization Flow

Standard Login Flow

Token Refresh Flow

The SDK automatically refreshes tokens before they expire:

Logout Flow

Tokens Explained

Access Token

  • Purpose: Authenticate API requests

  • Lifetime: Short (typically 15 minutes)

  • Storage: Stored in browser storage by SDK

  • Usage: Automatically included in API calls

Refresh Token

  • Purpose: Get new access tokens without re-login

  • Lifetime: Long (days to months)

  • Storage: Stored in browser storage by SDK

  • Usage: Automatically used by SDK when access token expires

ID Token

  • Purpose: Contains user identity information (JWT)

  • Lifetime: Same as access token

  • Storage: Stored in browser storage by SDK

  • Usage: SDK validates and decodes for user info

Scopes and Permissions

Scopes define what your application can access. The SDK automatically includes required scopes.

Common Scopes:

  • OPENID - Required for OIDC authentication

We're constantly adding new features and for those we're adding new scopes as well, so for the latest scopes and what they'll do please refer to the OPENID Configuration mentioned above and look for the key scopes_info.

App Registration

Before using the SDK, register your app on Deva to get credentials:

  1. Sign in to deva.me

  2. Navigate to Settings → Apps

  3. Click Create new app

  4. Provide required information:

    • App Name: Your application name

    • Description: Brief description

    • Redirect URIs: Where Deva redirects after login (e.g., http://localhost:3000)

    • Origin URIs: Where your app makes requests from (e.g., http://localhost:3000)

    • Scopes: Select required access permissions

  5. Save your client_id - you'll need this for the SDK

Note: You do not need a client_secret for the SDK. The PKCE flow eliminates the need for secrets in browser applications.

Learn step-by-step how to register your app

Security Best Practices

Implemented by SDK

  • PKCE Flow: Prevents authorization code interception

  • State Parameter: Prevents CSRF attacks (handled automatically)

  • Token Storage: Tokens stored securely in browser storage

  • Automatic Refresh: Tokens refreshed before expiration

Your Responsibility

  • HTTPS in Production: Always use HTTPS for production apps

  • Redirect URI Validation: Ensure redirect URIs are exact matches

  • Origin Whitelisting: Only whitelist trusted domains

  • Token Exposure: Never log or expose tokens in console/errors

Related Documentation

Core Concepts:

Getting Started:

Implementation:

External Resources:

PreviousProvider PatternNextDeva SSO

Last updated