Skip to main content

Quick Start

Get authentication working in 5 minutes.

1. Create a Realm​

Open the Admin Panel and create a new realm:

https://your-domain.com/admin

Navigate to Realms > Create. Give it a name (e.g. "My App"). VoxKey generates a UUID, RSA keys, and a Management API automatically.

Note your Realm UUID -- you'll need it for all endpoints.

2. Add an auth provider​

Go to your realm's Auth Providers tab and add at least one provider:

  • LoginPass -- for email/password authentication
  • Google / GitHub / Discord -- for social login (requires OAuth2 credentials from the provider's developer console)

3. Register an application​

Go to Applications > Create and choose the type:

TypeWhen to usePKCE
Traditional WebServer-side apps (Laravel, Rails, Django)Optional
SPAReact, Vue, Angular appsRequired
M2MBackend services, cron jobsN/A

Add your redirect URI (e.g. http://localhost:3000/callback).

Save the Client ID and Client Secret (for confidential clients).

4. Discover OIDC endpoints​

Fetch the OpenID Connect discovery document:

curl https://your-domain.com/oauth2/{realmUUID}/.well-known/openid-configuration

Response includes all endpoints:

{
  "authorization_endpoint": "/oauth2/{realmUUID}/code",
  "token_endpoint": "/oauth2/{realmUUID}/token",
  "userinfo_endpoint": "/oauth2/{realmUUID}/userinfo",
  "jwks_uri": "/oauth2/{realmUUID}/oidc/jwks",
  "introspection_endpoint": "/oauth2/{realmUUID}/introspect",
  "revocation_endpoint": "/oauth2/{realmUUID}/revoke"
}

5. Test the login flow​

Start authorization​

Redirect the user to the authorization endpoint:

https://your-domain.com/oauth2/{realmUUID}/code
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:3000/callback
  &scope=openid profile email
  &state=random_state_value
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

The user authenticates and is redirected back with an authorization code.

Exchange code for tokens​

curl -X POST https://your-domain.com/oauth2/{realmUUID}/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=http://localhost:3000/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET \
  -d code_verifier=PKCE_VERIFIER

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50...",
  "id_token": "eyJ..."
}

Fetch user info​

curl https://your-domain.com/oauth2/{realmUUID}/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Next steps​