> For the complete documentation index, see [llms.txt](https://sdkdocs.deva.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdkdocs.deva.me/core-concepts/authentication-flow.md).

# 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