GraphQL API

The Mallnline platform exposes a federated GraphQL API through the Gateway at http://localhost:30000/graphql. All 17 subgraphs are composed into a single unified schema.

Authentication

1. Obtain a Dev Token

The fastest way to get an authenticated session for API testing:

curl -s -X POST http://localhost:3008/auth/dev/token \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}' | jq .

Response:

{
	"session_token": "sess_a1b2c3d4...",
	"expires_in": 86400,
	"user": {
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"email": "user@example.com",
		"username": "user"
	}
}

Note: The dev token endpoint requires DEV_MODE=true in the auth service environment. It is enabled by default in local development and must never be enabled in production.

2. Use the Token

Pass the token as a Bearer header on all GraphQL requests:

curl -X POST http://localhost:30000/graphql \
  -H "Authorization: Bearer sess_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id email } }"}'

3. Optional Context Headers

External Tools

GraphiQL

1. Open the built-in GraphiQL at http://localhost:30000/graphql in your browser
2. Add a Authorization: Bearer <token> header in the Headers panel

Apollo Sandbox

1. Visit studio.apollographql.com/sandbox
2. Set endpoint to http://localhost:30000/graphql
3. Add default headers: Authorization: Bearer <token>

Postman / Insomnia

1. Set request URL to POST http://localhost:30000/graphql
2. Under Authorization, choose Bearer Token and paste your session_token
3. Set body to GraphQL mode

Schema Introspection

Run a full introspection query to explore the schema:

curl -s -X POST http://localhost:30000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name kind description } } }"}' | jq '.data.__schema.types | length'

Or use the introspection script:

node scripts/test/run_introspection.js

Quick Start Examples

Products

# List products for a Malet
query Products($maletId: ID!) {
	products(filter: { malet: { id: { eq: $maletId } } }, paging: { first: 10 }) {
		edges {
			node {
				id
				name
				slug
				price
				currency
				variants {
					id
					name
					sku
					inventory
				}
			}
		}
	}
}

Services & Bookings

# List services for a Malet
query Services($maletId: ID!) {
	services(filter: { malet: { id: { eq: $maletId } } }) {
		edges {
			node {
				id
				name
				slug
				price
				duration
				bookingType
			}
		}
	}
}

Malets (Stores)

# List Malets
query SearchMalets {
	malets(paging: { first: 5 }) {
		edges {
			node {
				id
				name
				verticalType
				isVerified
				themeConfig {
					primaryColor
					mode
				}
			}
		}
	}
}

Organizations

# Get organization with members
query Org($id: ID!) {
	organization(id: $id) {
		id
		name
		slug
		members {
			edges {
				node {
					id
					role
					user {
						id
						email
					}
				}
			}
		}
	}
}

Search (Meilisearch)

# Universal search across products, services, blogs, malets
query Search($query: String!, $limit: Int) {
	search(query: $query, limit: $limit) {
		results {
			id
			name
			type
			price
			maletName
			slug
		}
		estimatedTotalHits
		facetDistribution
	}
}

Cart (uCart)

# Add item to cart
mutation AddToCart($input: AddToCartInput!) {
	addToCart(input: $input) {
		id
		items {
			productId
			quantity
			price
		}
		subtotal
	}
}

Error Handling

GraphQL errors follow the standard format:

{
	"errors": [
		{
			"message": "Unauthorized",
			"extensions": {
				"code": "UNAUTHENTICATED"
			}
		}
	],
	"data": null
}

Common Error Codes

Subgraph Architecture

The gateway federates 17 subgraphs. Each subgraph owns its domain entities:

See individual subgraph docs in the Subgraphs section for detailed schema references.