Authentication

Hypery supports three authentication methods.

Authentication Methods

User API Keys

Simple keys for personal backend projects.

• Format: ak_...
• Created: Dashboard or /api/user/api-keys
• Best for: Personal scripts, backend services
• Billing: User's personal team credits

Learn more →

Team OAuth Tokens

Personal OAuth tokens for SDK use.

• Format: Standard OAuth access token
• Created: /api/teams/:id/oauth-tokens
• Best for: OpenAI SDK, Continue.dev, Replicate SDK
• Billing: Team credits

Learn more →

OAuth Apps

Third-party applications with user consent.

• Credentials: client_id + client_secret
• Created: Register app in dashboard
• Best for: SaaS apps, custom admin panels
• Billing: User's team credits (with optional per-app limits)

Learn more →

Quick Comparison

Which Should I Use?

Choose User API Keys if:

• Building a personal project
• Running backend scripts
• Want simple authentication

Choose Team OAuth Tokens if:

• Using OpenAI SDK, Replicate SDK
• Integrating with Continue.dev, Cursor, etc.
• Want long-lived tokens for tools

Choose OAuth Apps if:

• Building a SaaS product
• Need access to user data
• Building custom admin panels
• Require user consent

React apps

Building a React or Next.js frontend? Use the @hyperyai/sdk React SDK for drop-in sign-in, user profile, conditional rendering, and mode-aware billing popups — no need to wire the OAuth flow by hand.

Using in Code

All three methods use the same Authorization header:

// Works with API keys, OAuth tokens, or OAuth app access tokens
const response = await fetch('https://hypery.ai/api/v1/chat/completions', {
  headers: {
    'Authorization': `Bearer ${yourToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'Hello' }]
  })
})

# Works with all three authentication methods
response = requests.post(
    'https://hypery.ai/api/v1/chat/completions',
    headers={'Authorization': f'Bearer {your_token}'},
    json={
        'model': 'anthropic/claude-3.5-sonnet',
        'messages': [{'role': 'user', 'content': 'Hello'}]
    }
)

curl https://hypery.ai/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-3.5-sonnet", "messages": [{"role": "user", "content": "Hello"}]}'

Why Use OAuth?

• User consent - Users explicitly authorize your app
• Scoped access - Request only the permissions you need
• Secure - No need to handle user credentials
• Revocable - Users can revoke access anytime

OAuth Flow

1. Register your app in the Hypery dashboard
2. Request authorization - Redirect users to authorize your app
3. Exchange code for tokens - Get access and refresh tokens
4. Make API requests - Use access token to call APIs
5. Refresh tokens - Get new access tokens when they expire

Quick Example

// 1. Redirect to authorization
const authUrl = new URL('https://hypery.ai/api/oauth/authorize')
authUrl.searchParams.set('client_id', 'your_client_id')
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback')
authUrl.searchParams.set('response_type', 'code')
authUrl.searchParams.set('scope', 'ai:chat teams:read user:read')
authUrl.searchParams.set('state', 'random_state')
 
window.location.href = authUrl.toString()
 
// 2. Exchange code for token (in your backend)
const tokenResponse = await fetch('https://hypery.ai/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    redirect_uri: 'https://yourapp.com/callback'
  })
})
 
const { access_token } = await tokenResponse.json()
 
// 3. Use access token
const response = await fetch('https://hypery.ai/api/v1/chat/completions', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
})

Choosing Between API Keys and OAuth

Next Steps