Authentication

Aphelion uses Auth0 for secure authentication with JWT tokens. This guide covers authentication flows, token management, and role-based access control.

Overview

Auth0 (Recommended)

Production-ready OAuth2 flow with Auth0. Supports social logins, MFA, and enterprise SSO.

API Key (Dev/Test)

Simple API key authentication for development and testing. Not recommended for production.

Auth0 Configuration

Aphelion provides a pre-configured Auth0 tenant for quick setup. You can also use your own Auth0 tenant for custom branding and configuration.

ℹ️Pre-configured Auth0 Credentials

Domain: auth.aphl.ai

Client ID: UbXxpQBSr9AsqpS2ln2jzmsmamromaFC

Audience: https://aphelion-gateway.com

Get Auth0 Configuration

GET/v1/auth/config

curl https://api.aphl.ai/v1/auth/config

Response:

{
  "domain": "auth.aphl.ai",
  "clientId": "UbXxpQBSr9AsqpS2ln2jzmsmamromaFC",
  "audience": "https://aphelion-gateway.com",
  "scope": "openid profile email"
}

Authentication Flow

The Auth0 authentication flow consists of 5 steps:

Get Auth URL

Request the Auth0 authorization URL from the API

Redirect User

Send the user to Auth0's login page

Handle Callback

Receive the authorization code from Auth0

Exchange Token

Exchange the code for access and refresh tokens

Create Profile

Create or retrieve the user profile

Step 1: Get Authorization URL

GET/v1/auth/login

curl "https://api.aphl.ai/v1/auth/login?redirect_uri=https://yourapp.com/callback"

Response:

{
  "auth_url": "https://auth.aphl.ai/authorize?client_id=...&redirect_uri=...",
  "state": "abc123xyz"
}

Step 4: Exchange Code for Tokens

POST/v1/auth/callback

curl -X POST https://api.aphl.ai/v1/auth/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "v1.refresh.abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Access Token

Include the access token in the Authorization header for all API requests:

curl https://api.aphl.ai/v1/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Frontend Integration (React)

App.tsx

import { Auth0Provider } from '@auth0/auth0-react';

function App() {
  return (
    <Auth0Provider
      domain="auth.aphl.ai"
      clientId="UbXxpQBSr9AsqpS2ln2jzmsmamromaFC"
      authorizationParams={{
        redirect_uri: window.location.origin,
        audience: "https://aphelion-gateway.com",
        scope: "openid profile email"
      }}
    >
      <YourApp />
    </Auth0Provider>
  );
}

useAuth.ts

import { useAuth0 } from '@auth0/auth0-react';
import { Aphelion } from 'aphelion';

export function useAphelionClient() {
  const { getAccessTokenSilently, isAuthenticated } = useAuth0();

  const getClient = async () => {
    if (!isAuthenticated) {
      throw new Error('User not authenticated');
    }

    const token = await getAccessTokenSilently();
    return new Aphelion({ accessToken: token });
  };

  return { getClient, isAuthenticated };
}

Token Management

Token Expiration

Access tokens expire after 24 hours. Use refresh tokens to obtain new access tokens without requiring the user to log in again.

Validate Token

POST/v1/auth/validate

curl -X POST https://api.aphl.ai/v1/auth/validate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "valid": true,
  "user_id": "auth0|user123",
  "email": "user@example.com",
  "roles": ["user"],
  "expires_at": "2024-01-16T12:00:00Z"
}

Refresh Token

POST/v1/auth/refresh

curl -X POST https://api.aphl.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "v1.refresh.abc123..."
  }'

Role-Based Access Control

Aphelion supports multiple roles with different permissions:

Role	Description	Permissions
`user`	Default role for all users	Basic API access, sessions, memory
`pro`	Pro subscription users	Higher rate limits, analytics, priority support
`enterprise`	Enterprise customers	Unlimited access, custom SLAs, SSO
`admin`	Platform administrators	Full access, system management

User Profiles

Get Current User

GET/v1/auth/me

curl https://api.aphl.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "user_id": "auth0|user123",
  "email": "user@example.com",
  "name": "John Doe",
  "picture": "https://...",
  "roles": ["user"],
  "created_at": "2024-01-01T00:00:00Z",
  "subscription": {
    "tier": "pro",
    "valid_until": "2024-12-31T23:59:59Z"
  }
}

Update Profile

PUT/v1/auth/profile

curl -X PUT https://api.aphl.ai/v1/auth/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }'

Security Best Practices

⚠️Store tokens securely

Never store tokens in localStorage for production apps. Use httpOnly cookies or secure session storage.

ℹ️Use HTTPS

Always use HTTPS in production to prevent token interception.

✅Implement token refresh

Set up automatic token refresh to maintain seamless user sessions without requiring re-authentication.

Error Handling

Common authentication errors and how to handle them:

Status	Error	Solution
`401`	Token expired	Refresh the access token
`401`	Invalid token	Re-authenticate the user
`403`	Insufficient permissions	Check user role requirements
`429`	Too many requests	Implement exponential backoff

Next Steps

Sessions & Execution

Create sessions and execute tools

→

API Reference

Complete API documentation

→