# Authentication Flow

The Deva SDK handles user authentication automatically using OAuth 2.0, managing the entire lifecycle from login to token refresh without manual intervention.

***

## Overview

Authentication in the Deva SDK follows a simple pattern:

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

```
Note over User,Deva: Login Flow
User->>App: Click Login
App->>SDK: login()
SDK->>Deva: Redirect to login page
User->>Deva: Enter credentials
Deva->>SDK: Return auth tokens
SDK->>Deva: Fetch user data
Deva->>SDK: User profile
SDK->>App: Update auth state

Note over User,Deva: Authenticated Session
App->>SDK: Use components/hooks
SDK->>Deva: API requests (auto token)

Note over User,Deva: Auto Token Refresh
SDK->>SDK: Detect token expiring
SDK->>Deva: Refresh token request
Deva->>SDK: New access token

Note over User,Deva: Logout
User->>App: Click Logout
App->>SDK: logout()
SDK->>Deva: Revoke tokens
SDK->>App: Clear auth state" %}
```

**Authentication Stages:**

* **Login** - User authenticates with Deva account
* **Session** - Authenticated access to Deva platform
* **Refresh** - Automatic token renewal (background)
* **Logout** - Clean session termination

***

## Authentication Lifecycle

### 1. Initial State

When your app starts, users are unauthenticated. The SDK checks for stored credentials and may restore a previous session automatically.

### 2. Login Process

When a user initiates login:

* SDK redirects to Deva's secure login page
* User authenticates with their Deva account
* SDK receives authentication tokens
* User information is fetched and stored
* App state updates to authenticated

[Learn how to implement login](/authentication/login-implementation.md)

### 3. Authenticated Session

Once authenticated:

* User data is available via `useDeva()` hook
* Access tokens are included in API requests automatically
* SDK monitors token expiration
* Session persists across page refreshes

[Understand token management](/authentication/token-management.md)

### 4. Automatic Token Refresh

Before tokens expire:

* SDK detects upcoming expiration
* Refresh token is used to obtain new access token
* Process happens in the background
* User experience is uninterrupted

[Understand automatic token refresh](/authentication/token-management.md)

### 5. Logout

When a user logs out:

* Tokens are revoked on the server
* Local session data is cleared
* App state returns to unauthenticated

[Learn about logout handling](/authentication/logout-handling.md)

***

## How the SDK Manages Authentication

The **DevaProvider** component handles authentication automatically:

```tsx
<DevaProvider clientId="..." redirectUri="..." env="...">
  {/* Authentication state available throughout your app */}
</DevaProvider>
```

**What it manages:**

* OAuth flow (PKCE) for secure authentication
* Token storage and retrieval
* Automatic token refresh
* Session persistence
* Error handling

[Deep dive into OAuth](/authentication/oauth-integration.md)

***

## Access Authentication State

Use the `useDeva()` hook to access authentication information:

```tsx
const { isAuthenticated, user, login, logout } = useDeva();
```

**Available data:**

* `isAuthenticated` - Whether user is logged in
* `user` - User profile information
* `accessToken` - Current access token
* `login()` - Initiate login flow
* `logout()` - End user session

[Explore useDeva hook](/hooks-api/use-deva.md)

***

## Security Features

The SDK implements multiple security measures:

**OAuth 2.0 + OIDC**

* Industry-standard authentication protocol
* OpenID Connect for identity verification

**PKCE (Proof Key for Code Exchange)**

* Prevents authorization code interception
* Safe for browser-based applications
* No client secrets in frontend code

**Automatic Token Management**

* Short-lived access tokens (15 minutes)
* Secure refresh token rotation
* Server-side token revocation

[Learn about OAuth security](/authentication/oauth-integration.md)

***

## Common Patterns

### Protecting Routes

Check authentication status before rendering:

```tsx
if (!isAuthenticated) {
  return <LoginPrompt />;
}

return <ProtectedContent />;
```

### Loading States

Handle authentication initialization:

```tsx
const { isReady, isAuthenticated } = useDeva();

if (!isReady) {
  return <Loading />;
}
```

### Error Handling

Respond to authentication errors:

```tsx
const { authError } = useDeva();

if (authError) {
  return <ErrorMessage error={authError} />;
}
```

***

## Summary

The Deva SDK authentication flow:

1. **Starts unauthenticated** - Clean state on app load
2. **User initiates login** - Redirects to Deva SSO
3. **OAuth exchange** - Secure token retrieval
4. **Session active** - Full access to Deva platform
5. **Auto-refresh** - Seamless token renewal
6. **Logout available** - Clean session termination

Everything is handled automatically by the SDK - you only need to check authentication status and call `login()` or `logout()`.

***

## Learn More

* [**Deva SSO**](/authentication/deva-sso.md) - Why use Deva authentication
* [**OAuth Integration**](/authentication/oauth-integration.md) - Technical implementation details
* [**Login Implementation**](/authentication/login-implementation.md) - Add login to your app
* [**Token Management**](/authentication/token-management.md) - How tokens work
* [**Session Persistence**](/authentication/session-persistence.md) - Maintain user sessions


---

# 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/core-concepts/authentication-flow.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.