# 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

{% @mermaid/diagram content="sequenceDiagram
participant User
participant App
participant SDK
participant Deva SSO

```
User->>App: Click Login
App->>SDK: login()
SDK->>SDK: Generate code_verifier & code_challenge
SDK->>Deva SSO: Redirect to /authorize + code_challenge
Deva SSO->>User: Show login page
User->>Deva SSO: Enter credentials & consent
Deva SSO->>SDK: Redirect with authorization code
SDK->>Deva SSO: POST /token (code + code_verifier)
Deva SSO->>SDK: access_token, refresh_token, id_token
SDK->>Deva SSO: GET /userinfo (with access_token)
Deva SSO->>SDK: User profile data
SDK->>App: User authenticated" %}
```

***

### Token Refresh Flow

The SDK automatically refreshes tokens before they expire:

{% @mermaid/diagram content="sequenceDiagram
participant App
participant SDK
participant Deva SSO

```
SDK->>SDK: Check if token expired
SDK->>Deva SSO: POST /token (refresh_token)
Deva SSO->>SDK: New access_token & refresh_token
SDK->>SDK: Update stored tokens
App->>App: Continue using SDK normally" %}
```

***

### Logout Flow

{% @mermaid/diagram content="sequenceDiagram
participant User
participant App
participant SDK
participant Deva SSO

```
User->>App: Click Logout
App->>SDK: logout()
SDK->>Deva SSO: POST /revoke (access_token)
Deva SSO->>SDK: Success
SDK->>SDK: Clear stored tokens
SDK->>App: User logged out" %}
```

***

## 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](#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](https://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](/getting-started/quickstart.md#step-1-create-your-deva-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:**

* [Authentication Flow](/core-concepts/authentication-flow.md) - How authentication works
* [Provider Pattern](/core-concepts/provider-pattern.md) - Managing auth state

**Getting Started:**

* [Quickstart Guide](/getting-started/quickstart.md) - Get started with the SDK
* [Deva SSO](/authentication/deva-sso.md) - Why use Deva authentication

**Implementation:**

* [Login Implementation](/authentication/login-implementation.md) - Add login functionality
* [Logout Handling](/authentication/logout-handling.md) - Implement logout functionality
* [Token Management](/authentication/token-management.md) - Understand token lifecycle

**External Resources:**

* [OpenID Connect Specification](https://openid.net/connect/) - Official OIDC documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdkdocs.deva.me/authentication/oauth-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.