indiko documentation

overview

Indiko is a self-hosted IndieAuth/OAuth 2.0 authorization server with passwordless authentication using WebAuthn passkeys. It provides single sign-on (SSO) for your apps and services.

key features

• Passwordless authentication via WebAuthn passkeys
• Full IndieAuth and OAuth 2.0 support with PKCE
• Access tokens and refresh tokens for API access
• Token introspection and revocation endpoints
• UserInfo endpoint for profile data
• Auto-registration of OAuth clients
• Pre-registered clients with secrets and role management
• Session-based SSO (authenticate once, authorize many apps)
• User profile endpoints with h-card microformats
• Invite-based user registration

getting started

for app developers

To integrate with Indiko as an OAuth client, you'll need:

1. A client ID (any valid URL, e.g., https://myapp.example.com)
2. A redirect URI (where users return after authorization)
3. Support for PKCE (code challenge/verifier)

publishing client metadata (recommended)

To help Indiko verify your app and display proper branding, publish client metadata as JSON at your client_id URL:

{
  "client_id": "https://myapp.example.com/",
  "client_name": "My App",
  "logo_uri": "https://myapp.example.com/logo.png",
  "redirect_uris": [
    "https://myapp.example.com/callback",
    "https://myapp.example.com/auth/callback"
  ]
}

Alternatively, you can publish redirect URIs as HTML <link> tags:

<link rel="redirect_uri" href="https://myapp.example.com/callback" />

for users

You'll need an invite code to create an account. Once registered:

• Set up your passkey (fingerprint, face ID, or security key)
• Complete your profile (name, photo, website)
• Authorize apps to access your profile
• Manage app permissions from your dashboard

sign in button

Copy this themed button for your app's login page. It matches Indiko's visual style:

HTML + CSS

API endpoints

authorization endpoints

authentication endpoints

authorization flow

0. discovery (recommended)

Before starting authorization, clients should discover the authorization server's endpoints from the user's profile URL:

1. Fetch the user's profile URL (e.g., http://localhost:3000/u/username)
2. Look for <link rel="indieauth-metadata"> tag or HTTP Link: header
3. Fetch the metadata endpoint to get authorization_endpoint and token_endpoint

The metadata endpoint returns:

{
  "issuer": "http://localhost:3000",
  "authorization_endpoint": "http://localhost:3000/auth/authorize",
  "token_endpoint": "http://localhost:3000/auth/token",
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["profile", "email"]
}

1. redirect to authorization endpoint

GET http://localhost:3000/auth/authorize?response_type=code
					&client_id=https://myapp.example.com
					&redirect_uri=https://myapp.example.com/callback
					&state=random_state_string
					&code_challenge=base64url_encoded_challenge
					&code_challenge_method=S256
					&scope=profile email

2. user authenticates and approves

Indiko will:

• Check if user has an active session (if not, prompt for passkey login)
• Show consent screen with requested scopes
• Auto-approve if user previously authorized this app

3. redirect back with code

https://myapp.example.com/callback?code=short_lived_authorization_code
					&state=random_state_string
					&iss=http://localhost:3000

4. exchange code for token

POST http://localhost:3000/auth/token
					Content-Type: application/x-www-form-urlencoded

					grant_type=authorization_code
					&code=authorization_code
					&client_id=https://myapp.example.com
					&redirect_uri=https://myapp.example.com/callback
					&code_verifier=original_code_verifier
					&client_secret=your_client_secret (if pre-registered)

5. receive tokens and user profile

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "RT_abc123xyz...",
  "me": "http://localhost:3000/u/username",
  "profile": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "photo": "https://example.com/photo.jpg",
    "url": "https://jane.example.com"
  },
  "scope": "profile email",
  "iss": "http://localhost:3000",
  "role": "admin"
}

token management

Indiko provides a complete OAuth 2.0 token management system with access tokens, refresh tokens, introspection, and revocation.

refresh tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token without requiring user re-authentication:

POST http://localhost:3000/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=RT_abc123xyz...
&client_id=https://myapp.example.com

Response:

{
  "access_token": "new_access_token...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "me": "http://localhost:3000/u/username",
  "scope": "profile email",
  "iss": "http://localhost:3000"
}

token introspection

Resource servers can verify access tokens by calling the introspection endpoint:

POST http://localhost:3000/auth/token/introspect
Content-Type: application/json

{
  "token": "access_token_here"
}

Response (valid token):

{
  "active": true,
  "me": "http://localhost:3000/u/username",
  "client_id": "https://myapp.example.com",
  "scope": "profile email",
  "exp": 1640000000,
  "iat": 1639996400
}

Response (invalid token):

{
  "active": false
}

token revocation

Apps can revoke access or refresh tokens when users log out:

POST http://localhost:3000/auth/token/revoke
Content-Type: application/json

{
  "token": "access_or_refresh_token_here"
}

Response: HTTP 200 (always returns success, even if token doesn't exist)

userinfo endpoint

Fetch updated user profile information using an access token:

GET http://localhost:3000/userinfo
Authorization: Bearer access_token_here

Response (with profile and email scopes):

{
  "name": "Jane Doe",
  "photo": "https://example.com/photo.jpg",
  "url": "https://jane.example.com",
  "email": "jane@example.com"
}

scopes

roles

Roles enable role-based access control (RBAC) in your applications. Only pre-registered clients with client secrets support role assignment.

how roles work

• Roles are assigned by admins for specific user-app combinations
• Role strings are arbitrary (e.g., "admin", "editor", "viewer")
• Only one role per user per app
• Included in token response if assigned
• Your app interprets the role string and enforces permissions

defining app roles

Apps can define available roles in three ways:

• Disabled (default): Leave "Available Roles" empty. No roles can be assigned.
• Predefined roles: Specify allowed roles (one per line). Creates a dropdown for role selection, preventing typos.
• Default role: Automatically assign a role when users first authorize your app.

assigning roles

Roles can be assigned in multiple ways:

1. Default role (automatic): If configured, users automatically receive the default role on first authorization.
2. Via invite codes: Admins can create invites with pre-assigned roles for specific apps. New users automatically get those roles on signup.
3. Via admin dashboard: Admins can assign or change roles for existing users in the clients management interface.

client types

auto-registered clients

Any app can use Indiko without pre-registration. On first authorization, Indiko will:

• Validate the client ID (must be a valid URL per IndieAuth spec)
• Fetch client metadata from the client_id URL (if available)
• Validate redirect_uri against published redirect_uris (if different host)
• Extract and store client name and logo (if provided)
• Automatically register the client for future use

Auto-registered clients:

• Client ID format: Any valid URL (e.g., https://myapp.example.com)
• Authentication: MUST use PKCE only (no client secret)
• Limitations: Cannot use client secrets or role assignment

pre-registered clients

Admins can pre-register clients for advanced features. All pre-registered clients require a client secret and must also use PKCE.

Pre-registered clients:

• Client ID format: Generated with ikc_ prefix (e.g., ikc_xxxxxxxxxxxxxxxxxxxxx)
• Client secret format: Generated with iks_ prefix (shown once on creation)
• Authentication: MUST use both PKCE AND client_secret in token requests
• Role assignment: Admins can assign per-user roles for RBAC
• Available roles: Define which roles can be assigned (enforces dropdown selection)
• Default role: Automatically assigned to users on first authorization
• Metadata: Custom name, logo, description

OAuth tester

Test the OAuth flow with a live interactive client. This simulates how your app would integrate with Indiko.