feat: devex (#160)

* chore: update text with app types

* chore: improve client credential docs and refactor getting started

Author: einaralex

apps/customer/package.json

@@ -3,7 +3,7 @@
   "version": "0.7.4",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbo",
+    "dev": "next dev --turbo -p 5000",
     "build": "next build",
     "start": "next start",
     "lint": "next lint --fix",

apps/developer/docs/authorization.mdx

@@ -125,29 +125,148 @@ Further reading:
 
 ## Client credentials authorization
 
-> Note: client credentials are used to authenticate the application itself, not a user. This is useful when you want to access your own data. While you can access user data with client credentials, it is not recommended. Instead, use the authorization code flow to authenticate users.
+The Client Credentials flow is used for server-to-server authentication where your application acts on its own behalf, not on behalf of a specific user. This is the authentication method for both **Personal** and **White-label** app types.
 
-Confidential clients which can hide their credentials, e.g. backend servers, can be enlisted in Monerium's partner program, which enables them simultaneous access to multiple profiles which have granted authorization. These clients can get an access_token by submitting a POST or GET request to `/auth/token`:
+### When to Use Client Credentials
 
-```
- curl --location --request POST 'http://api.monerium.app/auth/token' \
+- **Personal apps**: Your application performs automated actions on your own Monerium account (e.g., backend scripts, scheduled jobs, internal tooling)
+- **White-label apps**: Your platform manages users and their payment accounts directly, with Monerium fully abstracted from end users
+
+:::warning Security Requirements
+Client credentials (`client_secret`) must be stored securely and never exposed in client-side code. Only use this flow in environments where you can securely store secrets, such as backend servers.
+:::
+
+### Authentication Flow
+
+The client credentials flow is simpler than OAuth, involving just two steps:
+
+1. **Request Access Token** - Exchange your credentials for an access token
+2. **Use Access Token** - Make API calls with the token
+
+### Step 1: Request an Access Token
+
+Submit a POST request to `/auth/token` with your `client_id` and `client_secret`:
+
+```sh
+curl --location --request POST 'https://api.monerium.dev/auth/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id=1234567890abcdef' \
   --data-urlencode 'client_secret=27b871f28ab834b6be75c21578b4c944527fe34fce3952dc59f9c928b8502ee8' \
   --data-urlencode 'grant_type=client_credentials'
 ```
 
-Response:
+**Successful Response:**
 
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "your-refresh-token"
+}
 ```
+
+| Field | Description |
+|-------|-------------|
+| `access_token` | The token to use for API requests |
+| `token_type` | Always "Bearer" |
+| `expires_in` | Token lifetime in seconds (typically 3600 = 1 hour) |
+| `refresh_token` | Token to request a new access token when it expires |
+
+**Error Response:**
+
+```json
 {
-  access_token: "your-access-token",
-  expires_in: 3600,
-  refresh_token: "your-refresh-token",
-  token_type: "Bearer"
+  "error": "invalid_client",
+  "error_description": "Client authentication failed"
 }
 ```
 
+| Error Code | Description |
+|------------|-------------|
+| `invalid_client` | Invalid `client_id` or `client_secret` |
+| `invalid_request` | Missing required parameters |
+| `unauthorized_client` | Client not authorized to use this grant type |
+
+### Step 2: Use the Access Token
+
+Include the access token in the `Authorization` header for all API requests:
+
+```sh
+curl --location 'https://api.monerium.dev/profiles' \
+  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
+```
+
+### Refreshing the Access Token
+
+When your access token expires, use the refresh token to obtain a new one without re-authenticating:
+
+```sh
+curl --location --request POST 'https://api.monerium.dev/auth/token' \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode 'grant_type=refresh_token' \
+  --data-urlencode 'refresh_token=your-refresh-token' \
+  --data-urlencode 'client_id=1234567890abcdef' \
+  --data-urlencode 'client_secret=27b871f28ab834b6be75c21578b4c944527fe34fce3952dc59f9c928b8502ee8'
+```
+
+The response will contain a new `access_token` and `refresh_token`.
+
+### Security Best Practices
+
+:::danger Keep Your Secrets Safe
+- **Never commit** `client_secret` to version control
+- **Store securely** using environment variables or secret management services (e.g., AWS Secrets Manager, HashiCorp Vault)
+- **Rotate regularly** - Generate new credentials periodically
+- **Use HTTPS only** - Never send credentials over unencrypted connections
+- **Monitor usage** - Watch for unusual API activity that might indicate compromised credentials
+:::
+
+### Complete Example
+
+Here's a complete Node.js example:
+
+```javascript
+// Store credentials in environment variables
+const CLIENT_ID = process.env.MONERIUM_CLIENT_ID;
+const CLIENT_SECRET = process.env.MONERIUM_CLIENT_SECRET;
+
+async function getAccessToken() {
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET
+  });
+
+  const response = await fetch('https://api.monerium.dev/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(`Authentication failed: ${error.error_description}`);
+  }
+
+  const { access_token, expires_in, refresh_token } = await response.json();
+  return { access_token, expires_in, refresh_token };
+}
+
+async function makeApiRequest(accessToken) {
+  const response = await fetch('https://api.monerium.dev/profiles', {
+    headers: { 'Authorization': `Bearer ${accessToken}` }
+  });
+
+  return response.json();
+}
+
+// Usage
+const { access_token } = await getAccessToken();
+const profiles = await makeApiRequest(access_token);
+console.log(profiles);
+```
+
 Endpoint documentation: [Access Token](docs/api#tag/auth/operation/auth-token)
 
 Further reading:

apps/developer/docs/getting-started.mdx

@@ -3,68 +3,150 @@ title: Getting Started
 id: getting-started
 ---
 
-# Monerium developer documentation
+# Getting Started
 
-## Introduction
+Welcome to Monerium! This guide will help you integrate the Monerium API to offer your users IBANs directly connected to their blockchain addresses. Enable seamless money transfers between bank accounts and blockchains over the SEPA network.
 
-This guide will help you get started with the Monerium API to offer your users IBAN's directly connected to their blockchain address. This enables a seamless experience to collect and send money between bank accounts and blockchains over the SEPA network.
+## Overview
 
-## Getting Started
+Before you begin, determine which integration type fits your needs:
 
-### Sign Up
+:::tip Choose Your Integration Type
 
-To get started, head over to our [Sandbox](https://sandbox.monerium.dev) and sign up.
+**Building a user-facing app?** → [OAuth](#oauth) - Users authenticate with their Monerium accounts
 
-### Creating an App
+**Automating your own account?** → [Personal](#personal) - Run scripts and backend jobs on your account
 
-Once signed up, head over the [developer portal](https://sandbox.monerium.dev/developers) and create an app.
+**Managing accounts for your users?** → [White-label](#white-label) - Full platform control, Monerium abstracted away
 
-### Obtaining Credentials
+:::
 
-After creating an app, you will receive two distinct sets of credentials, each tailored for specific use cases. Below is a breakdown of these credentials and guidance on how to use them effectively.
+---
+
+## Setup
+
+### 1. Create Your Account
+
+Head over to our [Sandbox](https://sandbox.monerium.dev) and sign up for a developer account.
+
+### 2. Create an App
+
+Once signed up, go to the [developer portal](https://sandbox.monerium.dev/developers) and create a new app. You'll need to select an app type based on your use case.
+
+---
+
+## App Types
+
+Choose the authentication flow that matches your integration needs:
+
+### 🔐 OAuth (User-facing Apps) {#oauth}
+
+**Authentication:** [Authorization Code Flow with PKCE (Proof Key for Code Exchange)](#auth-flow)
+
+**How it works:** Your app acts on behalf of Monerium users with their explicit consent. Users sign in with their Monerium credentials and grant your app permission to access their accounts.
+
+**Credentials you'll receive:**
+- `client_id` - Unique identifier for OAuth flows
+
+**Best for:**
+- Web applications
+- Mobile apps
+- Any app where users authenticate and control their own data
+
+**Pricing:** Free
+
+**Next steps:** [OAuth Implementation Guide →](./authorization)
+
+---
+
+### 🤖 Personal (Own Account) {#personal}
 
-### Types of Credentials
+**Authentication:** [Client Credentials Flow](#client-credentials)
 
-1. **Authorization Code Flow Credentials**
+**How it works:** Your app performs automated actions directly on your own Monerium account, such as processing payments or checking balances.
 
-   - `client_id`: A unique identifier for user authentication flows.
-   - **Use Case:** Designed for secure client-side applications, paired with PKCE (Proof Key for Code Exchange) to enhance security.
-   - **Ideal For:** User-facing applications such as web apps or mobile apps.
+**Credentials you'll receive:**
+- `client_id` - Unique identifier
+- `client_secret` - Secret key for authentication (keep secure!)
 
-2. **Client Credentials**
-   - `client_id` and `client_secret`: A pair of credentials used for server-to-server authentication.
-   - **Use Case:** Server-to-server authentication.
-   - **Ideal For:** Backend services and API integrations, where user interaction is not required.
+**Best for:**
+- Backend scripts
+- Scheduled jobs
+- Internal tooling and automation
 
-### Implementing Authorization Code Flow
+**Pricing:** Free
 
-1. Redirect users to the authorization flow.
-2. Handle the returned authorization code.
-3. Exchange the code for an access token.
+**Next steps:** [Client Credentials Guide →](./authorization#client-credentials-authorization)
 
-[In-depth guide](./authorization)
+---
+
+### 🏢 White-label (Managed Users) {#white-label}
+
+**Authentication:** [Client Credentials Flow](#client-credentials)
+
+**How it works:** Your platform manages users and their payment accounts directly. Monerium is fully abstracted away from your end users—they never see or interact with Monerium.
+
+**Credentials you'll receive:**
+- `client_id` - Unique identifier
+- `client_secret` - Secret key for authentication (keep secure!)
+
+**Best for:**
+- Payment platforms
+- Fintech applications
+- Services requiring full control over user payment flows
+
+**Pricing:** €5,000/month
+
+:::info Enterprise Solution
+This is an enterprise solution for platforms that want to offer IBAN accounts under their own brand. Contact us to discuss your requirements.
+:::
+
+**Next steps:** [Client Credentials Guide →](./authorization#client-credentials-authorization)
+
+---
+
+## Implementation Guides
+
+### OAuth - Authorization Code Flow with PKCE (Proof Key for Code Exchange) {#auth-flow}
+
+For user-facing applications using OAuth with PKCE:
+
+1. Redirect users to the Monerium authorization endpoint
+2. Handle the returned authorization code
+3. Exchange the code for an access token
+4. Use the access token to make API calls
 
-### Using Client Credentials
+**[📖 Read the OAuth guide →](./authorization)**
 
-For server-side authentication, follow these steps:
+### Client Credentials {#client-credentials}
 
-1.  Use the `client_id` and `client_secret` to authenticate your application.
-2.  Request an access token directly from the authorization server.
+For server-to-server authentication (Personal and White-label):
 
-[In-depth guide](./authorization#client-credentials-authorization)
+1. Securely store your `client_id` and `client_secret`
+2. Request an access token from the authorization server
+3. Use the access token to make API calls
 
-### Key Concepts and References
+**[📖 Read the Client Credentials guide →](./authorization#client-credentials-authorization)**
 
-- OAuth 2.0: The foundational framework for authorization. [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749).
+---
+
+## Additional Resources
+
+### Key OAuth Concepts
 
-- PKCE (Proof Key for Code Exchange): A security enhancement for public clients. [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)
+- **OAuth 2.0** - The foundational framework for authorization. [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
+- **PKCE** - Security enhancement for public clients. [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)
+- **Client Credentials Grant** - Server-to-server authentication flow. [RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
+- **Bearer Authentication** - Method for transmitting access tokens. [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
 
-- Bearer Authentication: A method for transmitting access tokens. [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
+### API Documentation
 
-## Next steps.
+Explore the complete API reference:
 
-Head over to the [API Documentation](./docs/api) to get started with the Monerium API.
+**[📖 View API Documentation →](./docs/api)**
+
+---
 
-## Need help?
+## Need Help?
 
-We have a [Discord server](https://monerium.com/invite/discord) where you can get help from the community and the Monerium team.
+Join our [Discord server](https://monerium.com/invite/discord) to get help from the community and the Monerium team.