Authentication

Learn how to authenticate with the Ryva API using JWT tokens from Supabase

Overview

The Ryva API uses JWT (JSON Web Tokens) for authentication, powered by Supabase Auth. Most endpoints require a valid JWT token in the request headers.

Authentication Flow

1. User signs up or logs in through Supabase Auth
2. Supabase returns a JWT access token
3. Include the token in the Authorization header for API requests
4. The API validates the token with Supabase

Getting a Token

Tokens are obtained through Supabase Auth. Here’s an example using the Supabase client:

JavaScript

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
)

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: '[e-mail]',
  password: 'secure-password'
})

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: '[e-mail]',
  password: 'secure-password'
})

// Access token
const token = data.session.access_token

Making Authenticated Requests

Include the JWT token in the Authorization header with the Bearer scheme:

cURL

curl https://api.ryva.com/v1/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Token Validation

The API validates tokens by:

1. Verifying the JWT signature using the Supabase JWT secret
2. Checking token expiration
3. Extracting user information from the token claims

Authentication Errors

Missing Token

{
  "error": {
    "message": "Missing authorization header",
    "code": "UNAUTHORIZED",
    "status": 401
  }
}

Invalid Token

{
  "error": {
    "message": "Invalid or expired token",
    "code": "UNAUTHORIZED",
    "status": 401
  }
}

Insufficient Permissions

{
  "error": {
    "message": "You don't have permission to access this resource",
    "code": "FORBIDDEN",
    "status": 403
  }
}

Token Lifecycle

Token Expiration

JWT tokens expire after a certain period (default: 1 hour). When a token expires, you’ll receive a 401 error.

Refreshing Tokens

Use Supabase’s refresh token mechanism to get a new access token:

const { data, error } = await supabase.auth.refreshSession()
const newToken = data.session.access_token

Revoking Tokens

Sign out to revoke the current session:

await supabase.auth.signOut()

Public Endpoints

Some endpoints don’t require authentication:

• GET /health - Health check
• POST /v1/waitlist - Join waitlist
• POST /v1/billing/webhooks/stripe - Stripe webhooks (verified by signature)

User Context

Authenticated requests automatically include user context:

• User ID: Extracted from the JWT sub claim
• Email: Extracted from the JWT email claim
• Roles: Determined by organization membership

The API uses this context to:

• Verify resource ownership
• Enforce role-based access control
• Audit actions

Security Best Practices

Never expose your JWT tokens in client-side code, logs, or version control.

1. Store tokens securely: Use secure storage mechanisms (e.g., httpOnly cookies, secure storage APIs)
2. Use HTTPS: Always make API requests over HTTPS in production
3. Implement token refresh: Refresh tokens before they expire
4. Handle errors gracefully: Catch authentication errors and prompt users to re-authenticate
5. Rotate secrets: Regularly rotate your Supabase JWT secret

Next Steps

Auth Endpoints

Manage user profiles and preferences

Organizations

Create and manage organizations