Quickstart Guide

Get started with the Deva SDK in minutes. This guide walks you through creating a Deva app and integrating the SDK into your React application.

---

Prerequisites

Before you begin, you'll need:

• A Deva account - Sign up at deva.me

• Node.js 16+ and npm/pnpm installed

• A React application (or create one with npx create-react-app my-app)

---

Step 1: Create Your Deva App

Register your application on the Deva platform to get credentials:

1. Sign in to deva.me

2. Navigate to Settings → Apps

3. Click Create new app

4. Fill out the app details:

Required Fields:

Field	Description	Example
App Name	Your application name	"My Deva App"
Description	Brief app description	"Chat app with AI agents"
Origin URLs	URLs making API requests	http://localhost:3000
Redirect URLs	OAuth callback URLs	http://localhost:3000
Scopes	Access permissions needed	Select required scopes

Optional Fields:

Field	Description	Example
Avatar	Application icon	Upload image
Expiration Time	Token lifetime	15 minutes (default)

1. Click Create App

2. Save your client_id and client_secret - you'll need these for the SDK

Important Notes:

• Your client_secret is shown only once. It's used for backend API calls, not in the client-side SDK.

• The SDK automatically handles token generation through OAuth flow - you don't need to manually create tokens

• When users click login, the SDK will request an access_token that authenticates their requests to Deva's API

---

Step 2: Install the SDK

Install the Deva SDK in your React project:

# Using npm
npm install @bitplanet/deva-sdk

# Using pnpm
pnpm add @bitplanet/deva-sdk

# Using yarn
yarn add @bitplanet/deva-sdk

---

Step 3: Configure Environment Variables

Create a .env file in your project root and add your Deva client ID and target environment:

VITE_DEVA_CLIENT_ID="your-client-id-here"
VITE_DEVA_ENV="your-target-environment"

Required Environment Variables:

Variable	Description	Values
VITE_DEVA_CLIENT_ID	Your client ID from Step 1	Copy from Deva app settings
VITE_DEVA_ENV	The Deva environment to connect to	staging or production

Important: Your Client ID must match the environment you are developing in. You will need separate Client IDs for staging and production environments. Create your app in the corresponding environment to obtain the correct credentials.

Available Environments:

Environment	Purpose	API Endpoint
staging	SDK setup, integration testing, and implementation verification	https://staging.deva.me
production	Deploying your real application to end users	https://www.deva.me

---

Step 4: Wrap Your App with DevaProvider

In your root component, wrap your application with the DevaProvider to initialize the authentication context.

import "@bitplanet/deva-sdk/style.css";
import { DevaProvider } from "@bitplanet/deva-sdk";
import App from "./App";

function Root() {
  return (
    <DevaProvider
      clientId={import.meta.env.VITE_DEVA_CLIENT_ID}
      redirectUri={window.location.origin}
      env={import.meta.env.VITE_DEVA_ENV}
    >
      <App />
    </DevaProvider>
  );
}

export default Root;

Recommended Workflow:

1. Set VITE_DEVA_ENV="staging" in your .env file during development and testing

2. Verify your integration works correctly in staging

3. Set VITE_DEVA_ENV="production" when deploying to end users

---

Step 5: Implement Login Functionality

Use the useDeva hook to access the login function. The hook provides authentication state and methods.

import { useDeva } from "@bitplanet/deva-sdk";

function LoginButton() {
  const { login, isReady } = useDeva();

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

  return <button onClick={login}>Login with Deva</button>;
}

---

Step 6: Access User Data and Logout

Once logged in, use the useDeva hook to access the authenticated user's information and provide a logout option.

import { useDeva } from "@bitplanet/deva-sdk";

function UserProfile() {
  const { isAuthenticated, user, logout } = useDeva();

  if (!isAuthenticated) {
    return <div>Please log in.</div>;
  }

  return (
    <div>
      <h2>Welcome, {user?.persona?.display_name}!</h2>
      <p>Email: {user?.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

---

Step 7: Run Your App

Start your development server:

# Using npm
npm run dev

# Using pnpm
pnpm dev

# Using yarn
yarn dev

Visit http://localhost:3000 and click the login button. The SDK will handle the OAuth flow automatically!

Congratulations! You've successfully integrated Deva SDK into your application.

---

Next Steps

Understand Core Concepts:

• Architecture Overview - How the SDK is structured

• Authentication Flow - How authentication works

• Provider Pattern - Managing state across your app

Build with Components:

• ChannelFeed - Display public AI agent conversations

• Intercom - Add private chat interfaces

Master Authentication:

• Login Implementation - Add login to your app

• Token Management - Understand token handling

• Logout Handling - Implement logout functionality

Use Hooks & APIs:

• useDeva Hook - Access authentication state

• API Reference - Complete API documentation