UltraVoiceDocs

Authentication

All API requests to the Gateway require a JWT Bearer token. Tokens are obtained via the Auth API after email verification.

ℹ️

A default workspace is automatically created when you verify your email. This workspace is used for knowledge base storage and agent organization.

Register

BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "first_name": "John",
    "last_name": "Doe"
  }'
JSON
{
  "success": true,
  "data": {
    "message": "OTP sent to [email protected]",
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Password Requirements

  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number

Verify Email (OTP)

After registration, a 6-digit OTP code is sent to your email. Verify within 10 minutes. Maximum 5 attempts.

BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "code": "482916"}'

Resend OTP

BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/resend-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Login

BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "SecurePass123!"}'
JSON
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Using Tokens

Include the access token in every API request:

BASH
curl https://ultravoice.us.inc/api/v1/agents/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh

Access tokens expire after 24 hours. Use the refresh token to get a new one without re-authenticating:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Get Current User

BASH
curl https://ultravoice.us.inc/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Security Best Practices

  • Never expose tokens in client-side code or version control
  • Always use HTTPS in production
  • Store tokens in httpOnly cookies or secure storage
  • Implement token refresh logic before the 24h expiry
  • Rotate JWT_SECRET regularly in production environments