Skip to main content

​
Overview

The Avala API uses API keys to authenticate requests. All API requests must include a valid API key, which you can obtain from the Avala dashboard.
Keep your API keys secure and never commit them to version control. Use environment variables or secret management tools.

​
Get your API key

1

Sign in to Avala

Navigate to app.avala.ai and sign in to your account.
2

Open API settings

Go to Settings → API Keys or visit app.avala.ai/settings/api-keys.
3

Create a new key

Click Create API Key, give it a descriptive name, and copy the generated key.
4

Store securely

Save the key in a secure location. You won’t be able to see it again after closing the dialog.
API keys are prefixed with avk_ to help identify them.

​
Authentication methods

The SDK supports two ways to provide your API key: Set the AVALA_API_KEY environment variable, and the SDK will automatically use it: 
export AVALA_API_KEY="avk_your_api_key"
Then initialize the client without any arguments: 
import Avala from "@avala-ai/sdk";

const avala = new Avala();
This is the recommended approach for production applications. It keeps secrets out of your code and makes it easy to use different keys for different environments.

​
Direct configuration

Alternatively, pass the API key directly when creating the client: 
import Avala from "@avala-ai/sdk";

const avala = new Avala({ 
  apiKey: "avk_your_api_key" 
});
Avoid hardcoding API keys in your source code. Use this method only for testing or when loading keys from a secure secret manager.

​
Environment-specific keys

Use different API keys for different environments (development, staging, production):
.env.development
AVALA_API_KEY=avk_dev_key_here
.env.production
AVALA_API_KEY=avk_prod_key_here
Load the appropriate .env file using a package like dotenv: 
import "dotenv/config";
import Avala from "@avala-ai/sdk";

const avala = new Avala();
Add .env* files to your .gitignore to prevent accidentally committing secrets.

​
Authentication errors

If your API key is invalid or missing, the SDK will throw an error: 
import Avala from "@avala-ai/sdk";

try {
  const avala = new Avala();
} catch (error) {
  console.error(error.message);
  // "No API key provided. Pass apiKey in config or set 
  // the AVALA_API_KEY environment variable."
}

​
Additional configuration

The SDK constructor accepts additional configuration options: 
import Avala from "@avala-ai/sdk";

const avala = new Avala({
  apiKey: "avk_your_api_key",
  baseUrl: "https://api.avala.ai/api/v1", // Custom base URL
  timeout: 60_000, // Request timeout in milliseconds (default: 30000)
});

​
Base URL configuration

You typically don’t need to change the base URL unless you’re working with a self-hosted Avala instance or a custom environment.
For local development, you may need to use an HTTP base URL: 
export AVALA_ALLOW_INSECURE_BASE_URL=true

const avala = new Avala({
  apiKey: "avk_your_api_key",
  baseUrl: "http://localhost:8000/api/v1"
});
The SDK enforces HTTPS by default for security. Non-HTTPS URLs are only allowed for localhost when AVALA_ALLOW_INSECURE_BASE_URL=true is set.

​
Request timeout

Adjust the timeout for long-running requests: 
const avala = new Avala({
  timeout: 60_000, // 60 seconds
});
The default timeout is 30 seconds. Increase it if you’re working with large exports or complex queries.

​
Creating a new account programmatically

The SDK includes a signup() function to create new Avala accounts programmatically. This is useful for automation or integration workflows. 
import { signup } from "@avala-ai/sdk";

const result = await signup({
  email: "[email protected]",
  password: "secure_password",
  firstName: "John",
  lastName: "Doe"
});

console.log("User created:", result.user.username);
console.log("API Key:", result.apiKey);

​
Parameters

​
options
SignupOptions
required
Account creation options
​
email
string
required
Email address for the new account
​
password
string
required
Password for the new account
​
firstName
string
User’s first name
​
lastName
string
User’s last name
​
baseUrl
string
Custom API base URL (defaults to production)
​
timeout
number
Request timeout in milliseconds (default: 30000)

​
Returns

​
user
SignupUser
Information about the created user
​
uid
string
Unique identifier for the user
​
username
string
Username for the account
​
email
string | null
User’s email address
​
firstName
string | null
User’s first name
​
lastName
string | null
User’s last name
​
inWaitlist
boolean
Whether the user is in the waitlist
​
apiKey
string
API key for the newly created account. Save this securely - you won’t be able to retrieve it again.
The signup() function does not require an existing API key. It returns an API key for the newly created account.

​
Security best practices

Store API keys in environment variables or secret management tools, never in source code.
Periodically rotate your API keys, especially if you suspect they may have been compromised.
Create separate API keys for development, staging, and production environments.
If your Avala plan supports it, create keys with limited scopes for specific use cases.
Track API key usage in the Avala dashboard to detect unusual activity.
If an API key is exposed, revoke it immediately from the dashboard and create a new one.

​
Next steps

Quick start guide

Make your first API call with the Avala SDK

API reference

Explore all available resources and methods

Build docs developers (and LLMs) love

Get started for freeTalk to us