Interna
Getting Started

Quick Start

Get up and running with Interna in under five minutes. This guide walks you through installation, configuration, and your first API call.

Prerequisites

Before you begin, make sure you have the following:

  • An Interna account — sign up if you don't have one.
  • An API key from your dashboard settings.
  • Node.js 18+ (for the JavaScript/TypeScript SDK).

Install the SDK

Install the Interna SDK using your preferred package manager:

Terminal
# npm
npm install @interna/sdk

# yarn
yarn add @interna/sdk

# pnpm
pnpm add @interna/sdk

Configure Your Client

Create and configure an Interna client instance. We recommend storing your API key as an environment variable rather than hardcoding it.

src/lib/interna.ts
import { Interna } from "@interna/sdk";

export const interna = new Interna({
  apiKey: process.env.INTERNA_API_KEY!,
  environment: "production",

  // Optional: configure retry behavior
  retries: 3,
  timeout: 10_000,
});

Environment Variables

Add the following to your .env.local file:

.env.local
INTERNA_API_KEY=sk_live_your_api_key_here
INTERNA_WEBHOOK_SECRET=whsec_your_webhook_secret

Make Your First Request

Let's verify everything works by listing the users in your organization:

src/app/api/users/route.ts
import { interna } from "@/lib/interna";
import { NextResponse } from "next/server";

export async function GET() {
  const users = await interna.users.list({
    limit: 10,
    orderBy: "created_at",
    direction: "desc",
  });

  return NextResponse.json(users);
}

Handling Responses

All list endpoints return a paginated response with a consistent shape:

Response
{
  "data": [
    {
      "id": "usr_2xK9mPqR",
      "email": "jane@acme.com",
      "name": "Jane Smith",
      "role": "admin",
      "created_at": "2025-01-15T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 10,
    "has_more": true
  }
}

Error Handling

The SDK throws typed errors that you can catch and handle appropriately:

error-handling.ts
import { Interna, InternaError } from "@interna/sdk";

try {
  const user = await interna.users.get("usr_nonexistent");
} catch (error) {
  if (error instanceof InternaError) {
    console.error(error.status);  // 404
    console.error(error.code);    // "user_not_found"
    console.error(error.message); // "No user found with that ID"
  }
}

See the Error Codes reference for a complete list of error codes and their meanings.

What's Next