Skip to content
MACHHUB MACHHUB MACHHUB
Contribute to this page

Authentication

Every authenticated request carries one of two credentials: a JWT obtained by logging in, or an API key. This page documents the login and permission endpoints and how to present each credential.

Endpoints

Section titled “Endpoints”
MethodPathPurpose
POST/auth/loginExchange username/password for a JWT
POST/machhub/auth/loginSame login, mounted on the data plane (used by the SDK)
GET/auth/permission/action/feature/:feature/scope/:scopeCheck the caller’s permission for a feature/scope

/auth/login and /machhub/auth/login are the same handler mounted on two prefixes — either works.

Logging in

Section titled “Logging in”

Send credentials as JSON:

POST /auth/login
Content-Type: application/json


{ "username": "admin", "password": "admin" }

On success the response contains a signed JWT in the tkn field:

{ "success": true, "tkn": "<jwt>" }

Bad credentials return 401 Unauthorized with a plain-text body (Invalid Username or Password); a malformed body returns 400 Bad Request.

sequenceDiagram
  participant App
  participant API as MACHHUB Platform
  App->>API: POST /auth/login { username, password }
  API-->>App: { success: true, tkn }
  App->>API: GET /machhub/products/all\nAuthorization: Bearer tkn
  API-->>App: [ ...records ]

Presenting a credential

Section titled “Presenting a credential”

Send one of these headers on each request.

JWT (Bearer token)

Section titled “JWT (Bearer token)”
Authorization: Bearer <jwt>

MACHHUB verifies the token’s signature on every request; the claims carry the user identity used for permission checks.

API key

Section titled “API key”
X-Machhub-Api-Key: mchx_<key-secret>

API keys are prefixed mchx_ and are created in the console (Account → Developer Keys). The full key is shown once at creation — store it securely.

Checking a permission

Section titled “Checking a permission”

The permission endpoint reports the caller’s effective access to a feature within a scope, using the permission model.

GET /auth/permission/action/feature/users/scope/all

The response reports the list of actions the caller is granted for that feature/scope:

{ "actions": ["read", "create", "update"] }

actions is an array of the granted action verbs (an empty array [] means no access). Actions are the domain’s configured verbs — built-ins such as read and read-write, plus any custom actions (e.g. export). The endpoint always returns 200 OK; inspect actions to decide what the caller may do.

Section titled “Related”