Skip to main content

​
Overview

Userorbit API uses two authentication methods depending on the endpoint type:
  1. API Key Authentication - For team/admin operations and Zapier integrations
  2. Subscriber JWT Authentication - For public widget and subscriber-specific operations

​
API Key Authentication

​
Getting Your API Key

  1. Log into your Userorbit dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Copy the generated key (you won’t be able to see it again)
  5. Store it securely (never commit to version control)

​
Using API Keys

Include your API key in the Authorization header using Bearer authentication: 
Authorization: Bearer team_api_key

curl https://api.userorbit.com/v1/feedbacks.list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
API Key Format

API keys follow this format: 
<random_38_characters>

​
API Key Permissions

Each API key is tied to:
  • A specific team (all operations are scoped to this team)
  • A user (for audit logging)
  • Permissions inherited from the user’s role

​
Best Practices

Security First: Never expose API keys in client-side code, public repositories, or logs.
  • Store keys in environment variables
  • Use separate keys for development and production
  • Rotate keys regularly (every 90 days recommended)
  • Delete unused keys immediately
  • Monitor API key usage in your dashboard

​
Subscriber JWT Authentication

​
Overview

Public/widget APIs require subscriber authentication to identify end-users and track their activity.

​
Getting a JWT Token

First, identify the subscriber using the subscriber.identify endpoint: 
curl https://api.userorbit.com/v1/public/subscriber.identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'
Response includes a JWT token: 
{
  "data": { ... },
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "isFirstSignin": true
}

​
Using JWT Tokens

Use the JWT token for subsequent subscriber operations: 
curl https://api.userorbit.com/v1/public/feedbacks.create \
  -H "Authorization: Bearer SUBSCRIBER_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Feature request",
    "text": "Add dark mode support"
  }'

​
JWT Token Lifespan

  • Tokens expire after 90 days
  • Automatically refreshed on widget initialization
  • Store securely in cookies or local storage (for web)

​
Subscriber Authentication Flow

​
Dual Authentication

Some endpoints support both authentication methods: 
# Using API key (team context)
curl https://api.userorbit.com/v1/public/documents.list \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using subscriber JWT (personalized results)
curl https://api.userorbit.com/v1/public/documents.list \
  -H "Authorization: Bearer SUBSCRIBER_JWT_TOKEN"
When authenticated with a subscriber JWT, the API returns personalized data (e.g., which documents the user has reacted to).

​
Error Responses

​
Invalid API Key

{
  "error": "Authentication required",
  "statusCode": 401
}

​
Expired JWT

{
  "error": "Token expired",
  "statusCode": 401
}

​
Missing Authorization

{
  "error": "Authentication required",
  "statusCode": 401
}

​
Testing Authentication

Test your API key: 
curl https://api.userorbit.com/v1/teams.info \
  -H "Authorization: Bearer YOUR_API_KEY"
Successful response confirms authentication: 
{
  "data": {
    "id": "team-uuid",
    "name": "Acme Corp",
    "subdomain": "acme"
  }
}

​
Revoking Access

​
Revoke API Keys

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click Delete
  4. Confirm deletion
All requests using the revoked key will immediately fail with 401 errors.

​
Invalidate JWT Tokens

Subscriber JWT tokens are automatically invalidated when:
  • The subscriber is deleted
  • The team is deleted
  • 90 days have passed since issuance

​
Security Considerations

Use HTTPS Only

Always make API requests over HTTPS to prevent key interception

Rotate Keys

Regularly rotate API keys (every 90 days recommended)

Least Privilege

Create separate keys with minimal permissions for each use case

Monitor Usage

Track API key usage and set up alerts for unusual activity

​
Next Steps