251 docs

Author: fengelniederhammer

lapis-docs/src/components/AuthenticationExamples.astro

@@ -0,0 +1,61 @@
+---
+import { Code, Aside } from '@astrojs/starlight/components';
+import { getLapisUrl } from '../lapisUrl';
+import { OnlyIf } from './OnlyIf.tsx';
+
+const lapisUrl = getLapisUrl();
+
+async function instanceRequiresAuthentication() {
+    try {
+        const response = await fetch(`${lapisUrl}/sample/info`);
+        return response.status === 401;
+    } catch (error) {
+        console.error('Error checking authentication requirement:', error);
+        return false;
+    }
+}
+
+const requiresAuth = await instanceRequiresAuthentication();
+---
+
+<Aside type='note'
+    >This LAPIS instance <b>{requiresAuth ? 'requires' : 'does not require'} authentication</b> to access its data.</Aside
+>
+
+<p>
+    Some LAPIS instances require authentication to access their data. If an instance is configured with authentication,
+    you need to include a valid access token in your requests.
+</p>
+
+<h2>Checking if Authentication is Required</h2>
+<p>Try accessing any endpoint without authentication:</p>
+
+<Code lang='bash' code={`curl ${lapisUrl}/sample/info -v`} />
+<p>
+    If authentication is required, you'll receive a <code>401 Unauthorized</code> response and the output will contains something
+    like
+</p>
+<Code code='> ...\n< HTTP/1.1 401\n< ...' />
+
+<p>If the instance is open (no authentication), you'll receive the normal response data.</p>
+
+<h2>Getting an Access Token</h2>
+
+<p>
+    Contact the LAPIS instance administrator to learn how to obtain an access token. The method depends on the identity
+    provider configured for that instance. Common methods include:
+    <ul>
+        <li><b>Username/password</b> - Exchange credentials for a token</li>
+        <li><b>Client credentials</b> - Use a client ID and secret</li>
+        <li><b>OAuth 2.0 flows</b> - Authorization code, device flow, etc.</li>
+    </ul>
+</p>
+
+<h2>Making Authenticated Requests</h2>
+<p>
+    To make authenticated requests to LAPIS, include the access token in the <code>Authorization</code> header using the <code
+        >Bearer</code
+    > scheme:
+
+    <Code lang='bash' code={`curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ${lapisUrl}/sample/aggregated`} />
+</p>

lapis-docs/src/components/UserAuthentication.astro

@@ -3,6 +3,6 @@ title: Authentication
 description: How to authenticate requests to LAPIS
 ---
 
-import AuthenticationExamples from '../../../components/AuthenticationExamples.astro';
+import UserAuthentication from '../../../components/UserAuthentication.astro';
 
-<AuthenticationExamples />
+<UserAuthentication />

lapis-docs/src/content/docs/concepts/authentication.mdx

@@ -27,11 +27,13 @@ LAPIS supports three methods for JWT validation:
 Specify the URL where LAPIS can fetch the public keys used to verify JWT signatures:
 
 **Example with Keycloak:**
+
 ```bash
 --spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://keycloak.example.com/realms/lapis/protocol/openid-connect/certs
 ```
 
 **When to use:**
+
 - You know the exact JWK Set endpoint URL
 - You want explicit control over the key source
 - Fastest startup (no auto-discovery needed)
@@ -42,11 +44,13 @@ Specify the OAuth 2.0 issuer URI,
 and LAPIS will auto-discover the JWK Set URI via the `.well-known/openid-configuration` endpoint:
 
 **Example with Keycloak:**
+
 ```bash
 --spring.security.oauth2.resourceserver.jwt.issuer-uri=https://keycloak.example.com/realms/lapis
 ```
 
 **When to use:**
+
 - You want LAPIS to auto-discover OAuth configuration
 - Your identity provider follows OpenID Connect standards
 
@@ -59,11 +63,13 @@ For testing or air-gapped environments, you can provide a PEM-encoded RSA public
 ```
 
 **When to use:**
+
 - Testing and development
 - Air-gapped deployments
 - Static key infrastructure
 
 **Public key format (RSA 2048-bit or higher):**
+
 ```
 -----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...