API Authentication

Every request to the Usermaven API must be authenticated. This guide explains how to obtain your credentials and how to include them in your requests.

1. Get your API credentials

Your API credentials are managed in your workspace settings.

1. Log in to your Usermaven account and go to Account Settings > API Credentials.

2. Click Create a new API key.

3. Give the key a descriptive name and click Generate API Key.

4. Copy and store the generated key securely. You will not be able to see the full key again after closing the page.

You have two credential values available to you:

Credential	Where to find it	Purpose
API Key	Account Settings > API Credentials	Authenticate REST API requests via the X-API-KEY header
Server Token	Settings → Workspace	Used together with the API key for server-side APIs (e.g. Event mutations)

2. Authenticate REST API requests

Pass your API key as a header parameter named X-API-KEY:

curl -X GET \
    https://api.usermaven.com/v1/workspaces \
  -H 'X-API-KEY: <API_KEY>'

Node.js example

const response = await fetch('https://api.usermaven.com/v1/workspaces', {
  headers: {
    'X-API-KEY': process.env.USERMAVEN_API_KEY
  }
});

Python example

import requests

response = requests.get(
    "https://api.usermaven.com/v1/workspaces",
    headers={"X-API-KEY": "YOUR_API_KEY"}
)

3. Server-side APIs (API Key + Server Token)

Some server-side APIs, such as the Event mutations API, require a combined authentication token composed of your API Key and Server Token.

Your authentication token format is:

API_KEY.SERVER_TOKEN

For example, if your API key is 1a2b3c4d and your server token is ef5g6h7i, your token is 1a2b3c4d.ef5g6h7i.

Important: Server-side APIs must only be used from a trusted backend environment. Never expose your API key or server token in client-side code, browsers, or public applications.

4. Security best practices

• Keep your API keys and server tokens secret; never commit them to source control.

• Use environment variables or a secrets manager.

• Restrict access to the minimum set of keys needed.

• Rotate keys periodically and revoke any key that may have been exposed.