🧰 Gateway Service

As we abstract more of our work into microservices to make them usable accross applications we need a central place to handle things like authentiacation, logging, elerts and so on. The gateway is a proxy to any other downstream services we have.

https://gateway.hexlabs.co.uk

This document explains how our gateway service is structured, deployed, and consumed. This service is the backend plumbing behind our platform — abstracted, modular, and boring (in a good way).

What does it do?

The gateway is essentially just a proxy that handles authentication, company API keys and so on. It will take a request for any internal services we have, authenticate you, then forward that request to the downstream service.

API

Postman Request Collection

Usage

const gatewayUrl = "https://gateway.hexlabs.co.uk"

const res = await $fetch(gatewayurl, {
    method: "post" // any http method
    headers: {
        // api key required.
        authorization: `bearer ${config.hexlabs_key}`,

        // ...headers
    },
    query: {
        service: "<service-name>", // default: "gateway"
        target: "<target-endpoint>", // default:  "/"
        version: "<version-number", // default: "v1"

        // ...query
    },

    // ...other http options
})

Output

Here is an example response from the PDF service, you can see that it includes data, the response from the downstream service, along with the meta which is the response from the gateway itself.

The gateway will always log error stack traces and give you some details about the request. For example the entire constructed URL its targeting.

const res = await $fetch(gatewayurl, {
    method: "post"
    headers: {
        Authorization: `Bearer ${config.HEXLABS_KEY}`,
    },
    query: {
        service: "pdf",
        // target left undefined // defaults to "/"
    },
})
{
    "data": {
        "id": "kdu4czv5afd69qkw",
        "size": 21475,
        "mime": "application/pdf",
        "timestamp": 1751205481740,
        "lastModified": 1751205481740,
        "previewUrl": "https://storage.googleapis.com/pdf-service-126df.firebasestorage.app/test-file-1751205480558-preview.pdf?GoogleAccessId=pdf-service-126df%40appspot.gserviceaccount.com&Expires=1751209081&Signature=ky8wfBmL%2FyHfIl5oPvWzNaj%2FTG7y53A7UvJrtJQoMEuWxzMHk2%2BTCCv9M56CwaWHyTlmDz%2BHzr8vwh%2BEFsAm2F0Ib6b17wZw6i2SlzsCpg%2BvPUuAywIfkoWS3tC%2F8WDBVGhqAGiQOUvBtxlAExuGdAFUO3pD2X9Qt9Mx%2FIyo%2Fpdtg50%2BLAwIudEPq%2BtLlidbo%2F%2BpbNbszAZkCdxmyEUUikm8jUsvzGMAJ63IOh%2Bj0VW3fk%2F8mBmsuCDcUFG0GokyQfMTg2Yul2WB73aRc7b5PjegG4v4mOeN9uTHbuouXzxq%2B7E9Oek7vE2wJI0FF2HllIylFAkf7eq8WmCDcoCCXg%3D%3D",
        "downloadUrl": "https://storage.googleapis.com/pdf-service-126df.firebasestorage.app/test-file-1751205480560-download?GoogleAccessId=pdf-service-126df%40appspot.gserviceaccount.com&Expires=1751209081&Signature=GROD%2Flp1Fk%2Fbomghc2HGq%2FQ4ytvvpzNDLBqgbtkJT%2BzfO2hIFwh7kyIcKAoE8VQ5UDNUXABcCjRBLDLdFhc9uXt2RmXG5hunD0RsmmATRFhLMcQygpEozTkNUJvyK8CfHh%2BNCFpFUl65ftG8MT66WTF7VFalJcVGrulBlZZfyqneBbdHtQ%2FQ7hQZfIQNG6h7ClWWKoNZlKIwoTCqRkY%2F2Iv4VHicZO%2BuEoE7t7pfC73jqWldyPkyKYuen4Wgw38zn4EZk8AMVf%2F5ZmIVgxmcTt0shuMGMMheKVsps7pcFHkPyJDRpWl%2Fkhlf1%2FHeXYiY9Zfkcs20%2F9PBQH2lJjjvQA%3D%3D",
        "name": "test-file"
    },
    "meta": {
        "log": [],
        "requestId": "e59aebf5-5b16-44ac-9425-1ed04f79c5fb",
        "gateway": "hexlabs",
        "targetService": "pdf",
        "targetVersion": "v1",
        "targetUrl": "https://pdf.hexlabs.co.uk/v1/",
        "timestamp": 1751205481769
    }
}

Or use the PDF SDK

Here is another example of an email requst.

const res = await $fetch(gatewayurl, {
    method: "post"
    headers: {
        Authorization: `Bearer ${config.HEXLABS_KEY}`,
    },
    query: {
        service: "email",
        target: "send",
    },

    body: {
        "to": ["codypwakeford@gmail.com"],
        "from": "cody@codywakeford.com",
        "subject": "Hello from email service!",
        "message": "hello friends"
    }
})


// Output
{
    "meta": {
        "log": [],
        "requestId": "deaf1241-b04b-4f9a-9b21-b439a1631df4",
        "gateway": "hexlabs",
        "targetService": "email",
        "targetEndpoint": "send",
        "targetVersion": "v1",
        "targetUrl": "https://email.hexlabs.co.uk/v1/send",
        "timestamp": 1751205617940
    }
}

Or use the Email SDK