Authentication

Miridia accepts two credentials:

• A bearer token acts for a person. Use it in an application where a person logs in.
• An API key acts for your organisation, without a person. Use it for a server, a script, or a connector.

The Global API issues both credentials. The Core API accepts both.

Log in

Send the email address and the password of the user to POST /api/auth/login on the Global API.

curl -X POST https://global.miridia.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"<your-password>"}'

The response has one of two shapes.

{
  "data": {
    "requiresOrganizationSelection": false,
    "session": {
      "accessToken": "eyJhbGciOiJSUzI1NiIs...",
      "expiresAtUtc": "2026-09-29T09:00:00Z",
      "organization": { "id": "...", "slug": "your-company", "name": "Your Company" }
    }
  },
  "statusCode": 200,
  "messages": []
}

{
  "data": {
    "requiresOrganizationSelection": true,
    "selectionToken": "eyJhbGciOiJSUzI1NiIs...",
    "selectionExpiresAtUtc": "2026-09-29T08:05:00Z",
    "organizations": [
      { "id": "0f8e...", "slug": "north", "name": "North Ltd", "isOwner": true },
      { "id": "7c21...", "slug": "south", "name": "South Ltd", "isOwner": false }
    ]
  },
  "statusCode": 200,
  "messages": []
}

curl -X POST https://global.miridia.io/api/auth/select-organization \
  -H "Authorization: Bearer $SELECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"0f8e..."}'

Send a bearer token

Send the access token in the Authorization header. Send the business in the X-Business-Id header.

curl https://api.miridia.io/api/v1/purchase-orders \
  -H "Authorization: Bearer $MIRIDIA_TOKEN" \
  -H "X-Business-Id: $MIRIDIA_BUSINESS_ID"

To find the businesses of the user, send GET /api/me to the Core API. This operation does not need the X-Business-Id header.

Refresh the session

An access token is valid for a short time. The value of expiresAtUtc tells you when it expires. The login response also sets a refresh cookie. To get a new access token, send POST /api/auth/new-token with that cookie. A browser application sends the cookie automatically.

To end the session, send POST /api/auth/logout.

Use an API key

An API key does not expire unless you give it a time to live. It is the correct credential for a system that calls Miridia.

curl -X POST https://global.miridia.io/api/auth/tokens \
  -H "Authorization: Bearer $MIRIDIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Warehouse scanner","businessId":"<business-id>","ttlMinutes":null,"scopes":null}'

curl https://api.miridia.io/api/v1/Products \
  -H "x-dispatch-api-key: $MIRIDIA_API_KEY"

Limit a key with scopes

A scope gives the key a permission on one module. The bitmask adds the actions: 1 is view, 2 is modify, and 4 is delete. For example, 7 gives all three actions.

{ "Products": 1, "PurchaseOrders": 3 }

This key can read products. It can read and change purchase orders. It cannot do anything else.

The modules are Orders, Shipments, Customers, Products, Vehicles, Integrations, TeamAndRoles, Billing, Workflows, Settings, Insights, Suppliers, PurchaseOrders, WorkOrders, TransferOrders, and Schedule. Each operation in the reference tells you the permission that it needs.

List and revoke keys

• To list the keys of your organisation, send GET /api/auth/tokens.
• To revoke a key, send DELETE /api/auth/tokens/{id}. The key stops at once.

Permissions

Each operation of the Core API needs a permission on one module, for example PurchaseOrders view. The role of the user gives the permissions of a bearer token. The scopes give the permissions of an API key.

If the credential does not have the permission, the API returns 403. Read Users and roles for the roles.

Errors

Read Conventions for the error body.

Reference

• Global API: Authentication
• Global API: Organizations