Authentication

Manage user accounts and session tokens via Better Auth. Registration creates a new organization with the registering user as org_owner. Supports email/password and OAuth (Google, GitHub) sign-in.

Elydora uses Better Auth for all authentication. There are two ways to authenticate depending on your client type:

Browser clients: Better Auth sets secure, httpOnly session cookies automatically. No manual token handling required.
API / SDK clients: Use the session token (el_sess_*) in the Authorization: Bearer header for programmatic access.
OAuth sign-in: Sign in with Google or GitHub via the /api/auth/sign-in/social endpoint. Better Auth handles the full OAuth flow.

Sign Up with Email

POST

/api/auth/sign-up/email

Create a new organization and user account via Better Auth email sign-up.

Request Body

Field	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	Password (min 8 characters)
name	string	Yes	User display name
org_name	string	Yes	Organization display name

Example Request

bash

curl -X POST https://api.elydora.com/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "s3cureP@ssw0rd",
    "name": "Admin User",
    "org_name": "Acme Corp"
  }'

Response

json

{
  "token": "el_sess_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCD",
  "user": {
    "id": "usr_abc123",
    "email": "admin@acme.com",
    "orgId": "org_acme",
    "role": "org_owner"
  }
}

Sign In with Email

POST

/api/auth/sign-in/email

Authenticate with email and password via Better Auth to receive a session token.

Request Body

Field	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password

Example Request

bash

curl -X POST https://api.elydora.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "s3cureP@ssw0rd"
  }'

Response

json

{
  "token": "el_sess_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCD"
}

Get Current Session

GET

/api/auth/session

Returns the authenticated user's profile and session details. For browser clients, the session cookie is sent automatically.

Auth: Any authenticated user

Example Request

bash

curl https://api.elydora.com/api/auth/session \
  -H "Authorization: Bearer <session-token>"

Response

json

{
  "id": "usr_abc123",
  "email": "admin@acme.com",
  "orgId": "org_acme",
  "role": "org_owner",
  "createdAt": "2026-01-15T10:30:00Z"
}

Sign In with OAuth

POST

/api/auth/sign-in/social

Initiate an OAuth sign-in flow with a supported provider (Google or GitHub). Better Auth handles the redirect and callback.

Request Body

Field	Type	Required	Description
provider	string	Yes	OAuth provider: "google" or "github"
callbackURL	string	Yes	URL to redirect to after successful authentication

Example Request

bash

curl -X POST https://api.elydora.com/api/auth/sign-in/social \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "callbackURL": "https://console.elydora.com/auth/callback"
  }'

Response

json

{
  "url": "https://github.com/login/oauth/authorize?client_id=...&redirect_uri=...",
  "redirect": true
}

Refresh Session

POST

/api/auth/session/refresh

Refresh the current session token to extend its expiry. For browser clients, the session cookie is refreshed automatically.

Auth: Any authenticated user

Example Request

bash

curl -X POST https://api.elydora.com/api/auth/session/refresh \
  -H "Authorization: Bearer <session-token>"

Response

json

{
  "token": "el_sess_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCD"
}

Issue API Token

POST

/v1/auth/token

Issue a dedicated API token with a custom expiration. Use this for long-lived agent tokens instead of session tokens. Requires an active Better Auth session.

Auth: Any authenticated user

Request Body

Field	Type	Required	Description
ttl_seconds	number \| null	No	Token lifetime in seconds. Pass null for a token that never expires. Defaults to null if omitted.

Example Request

bash

# Issue a 7-day token
curl -X POST https://api.elydora.com/v1/auth/token \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 604800}'

# Issue a never-expiring token
curl -X POST https://api.elydora.com/v1/auth/token \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": null}'

Response

json

{
  "token": "el_sess_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCD",
  "expires_at": 1740700800
}

expires_at is a Unix timestamp (seconds). It is null when ttl_seconds is null.