# DevaProvider

The `DevaProvider` is the root component that manages authentication, user state, and provides context to all SDK components and hooks.

***

## Import

```tsx
import { DevaProvider } from "@bitplanet/deva-sdk";
```

***

## Props

### clientId

**Type:** `string`

**Required:** Yes

Your application's OAuth client ID from Deva.

**How to get:**

1. Sign in to [deva.me](https://deva.me)
2. Navigate to **Settings → Apps**
3. Create new app or use existing
4. Copy the `client_id`

***

### redirectUri

**Type:** `string`

**Required:** Yes

The URI where Deva redirects after authentication.

**Requirements:**

* Must be registered in your Deva app settings
* Must be an absolute URL
* Must match exactly (including trailing slash)

**Examples:**

```tsx
// Development
redirectUri="http://localhost:3000"

// Production
redirectUri="https://myapp.com"
```

***

### env

**Type:** `"staging" | "production"`

**Required:** Yes

The Deva API environment to connect to. Set via the environment variable.

**Available Environments:**

| Environment    | Purpose                                                               | API Endpoint              |
| -------------- | --------------------------------------------------------------------- | ------------------------- |
| `"staging"`    | For SDK setup, integration testing, and verifying your implementation | `https://staging.deva.me` |
| `"production"` | For deploying your real application to end users                      | `https://www.deva.me`     |

**Configuration:**

```bash
# In your .env file
VITE_DEVA_ENV="staging"   # For development/testing
VITE_DEVA_ENV="production" # For live deployment
```

***

### children

**Type:** `React.ReactNode | ((devaProps: UseDevaReturn) => React.ReactNode)`

**Required:** Yes

Your application components. Supports both standard children and render prop pattern.

**Standard Pattern:**

```tsx
<DevaProvider {...props}>
  <App />
</DevaProvider>
```

**Render Prop Pattern:**

```tsx
<DevaProvider {...props}>
  {({ isAuthenticated, user }) => (
    <App isAuthenticated={isAuthenticated} user={user} />
  )}
</DevaProvider>
```

***

## Usage

### Basic Setup

```tsx
import { DevaProvider } from "@bitplanet/deva-sdk";

export default function Root() {
  return (
    <DevaProvider
      clientId="your-client-id"
      redirectUri={window.location.origin}
      env="your-target-environment"
    >
      <App />
    </DevaProvider>
  );
}
```

### With Environment Variables (Next.js)

```tsx
const devaConfig = {
  clientId: process.env.NEXT_PUBLIC_DEVA_CLIENT_ID!,
  redirectUri: process.env.NEXT_PUBLIC_DEVA_REDIRECT_URI!,
  env: process.env.NEXT_PUBLIC_DEVA_ENV as "staging" | "production"
};

<DevaProvider {...devaConfig}>
  <App />
</DevaProvider>
```

### With Render Props

```tsx
<DevaProvider
  clientId="your-client-id"
  redirectUri="your-redirect-uri"
  env="your-target-environment"
>
  {({ isAuthenticated, isReady, user }) => {
    if (!isReady) {
      return <LoadingScreen />;
    }

    if (!isAuthenticated) {
      return <LoginPage />;
    }

    return <AuthenticatedApp user={user} />;
  }}
</DevaProvider>
```

***

## What It Provides

The `DevaProvider` manages and provides:

### Authentication State

* OAuth 2.0 + OIDC authentication flow
* Access token management
* Refresh token handling
* Session persistence (sessionStorage)

### User Information

* User profile data
* User persona information
* Authentication status

### Context Values

All child components and hooks can access:

* `isAuthenticated` - Boolean authentication status
* `isReady` - Boolean indicating SDK initialization complete
* `accessToken` - Current access token (or null)
* `user` - User information (or null)
* `login()` - Function to initiate login
* `logout()` - Function to log out

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

***

## Internal Behavior

### Initialization Flow

1. **Component Mounts**
   * Loads OpenID configuration
   * Checks sessionStorage for existing tokens
   * Validates stored tokens
2. **Session Restoration**
   * If valid tokens exist, restores session
   * Fetches user information
   * Sets `isAuthenticated` to true
3. **Ready State**
   * Sets `isReady` to true when initialization complete
   * Components can now safely render

### Token Management

**Automatic Refresh:**

* Checks token expiration every second
* Refreshes tokens before expiration
* Updates sessionStorage automatically

**Session Storage:**

* Stores access\_token, refresh\_token, id\_token
* Stores expiration times
* Cleared on logout or browser close

### OAuth Flow

**Login Process:**

1. Generate PKCE code verifier and challenge
2. Redirect to Deva authorization endpoint
3. User authenticates and grants permissions
4. Deva redirects back with authorization code
5. Exchange code for tokens
6. Fetch user information
7. Store tokens in sessionStorage

**Logout Process:**

1. Revoke access token via revocation endpoint
2. Clear sessionStorage
3. Reset authentication state

***

## Error Handling

The provider handles errors internally:

**OpenID Config Load Failure:**

* Provider initialization fails
* App cannot authenticate users
* Consider showing error message

**Token Refresh Failure:**

* User is logged out automatically
* Session cleared
* User must log in again

**Network Errors:**

* Provider retries automatically
* Authentication state preserved when possible

***

## Best Practices

**Placement:**

* Place at the root of your application
* Only one provider per app
* Wrap entire app, not individual routes

**Environment Variables:**

* Store credentials in environment variables
* Never commit credentials to version control
* Use different credentials per environment

**Error Boundaries:**

```tsx
<ErrorBoundary>
  <DevaProvider {...config}>
    <App />
  </DevaProvider>
</ErrorBoundary>
```

**Loading States:**

```tsx
<DevaProvider {...config}>
  {({ isReady, isAuthenticated }) => {
    if (!isReady) return <Loading />;
    if (!isAuthenticated) return <Login />;
    return <App />;
  }}
</DevaProvider>
```

***

## TypeScript Interface

```typescript
type DevaProviderProps = {
  clientId: string;
  redirectUri: string;
  children: React.ReactNode | ((devaProps: UseDevaReturn) => React.ReactNode);
  env: "staging" | "production";
};

type UseDevaReturn = {
  isAuthenticated: boolean;
  isReady: boolean;
  accessToken: string | null;
  user: UserInfo | null;
  login: () => Promise<void>;
  logout: () => Promise<void>;
};
```

***

## Related Documentation

* [useDeva Hook](/hooks-api/use-deva.md) - Access provider state
* [Authentication Flow](/core-concepts/authentication-flow.md) - How auth works
* [OAuth Integration](/authentication/oauth-integration.md) - OAuth details
* [Provider Pattern](/core-concepts/provider-pattern.md) - Context pattern
* [Quickstart](/getting-started/quickstart.md) - Setup guide


---

# 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/api-reference/deva-provider.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.