Authentication

​

How the key is sent

GET /v1/me HTTP/1.1
Host: api.muveya.com
Authorization: Bearer mvy_test_EXAMPLE...

• The key is an opaque string, not a JWT. Do not decode it.
• Authorization: Bearer is the only accepted transport. There is no X-API-Key header and no query parameter for the key.
• The scheme name is not case sensitive, but the key itself must be sent exactly as issued, with no quotes and no line breaks.

​

What a key looks like

mvy_test_<24 letters and digits>_<4 letters and digits>

​

One key, one dental clinic

1. No request names a dental clinic. No /v1 path, query parameter or header accepts a tenant or workspace id. GET /v1/me tells you which dental clinic the key reads, as workspaceId.
2. A key reads the whole dental clinic. It is not limited by the location and warehouse access that applies to team members: within its scopes, it reads every location and every warehouse.
3. To integrate two dental clinics, use two keys. A record of another dental clinic answers 404, exactly as if it did not exist.

​

Get a key

​

The key depends on its member and its dental clinic

• If that member is suspended or removed from the dental clinic, the key stops working immediately.
• Reactivating the member does not bring the key back. The console says so when you reactivate someone: API keys from before the suspension stay closed. Request a new key.
• If the dental clinic itself is suspended, every one of its keys is refused.

​

Your first call: GET /v1/me

curl https://api.muveya.com/v1/me \
  -H "Authorization: Bearer $MUVEYA_API_KEY"

const response = await fetch("https://api.muveya.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.MUVEYA_API_KEY}` },
});
console.log(response.status, await response.json());

import os
import requests

response = requests.get(
    "https://api.muveya.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MUVEYA_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

{
  "workspaceId": "66d0a1f0c0ffee0000000001",
  "environment": "test",
  "scopes": ["clinics:read", "catalog:read", "inventory:read"]
}

​

Keep keys on your server

• Keep the key in a secret manager or in a server environment variable, and read it at runtime.
• Never put it in browser code, a mobile app, a shared spreadsheet, a code repository, a URL, a log line or an error report.
• Use one key per integration, so that you can revoke one without stopping the others.
• When you talk to support about a key, identify it by its name or its prefix (the first 12 characters), never by the full key.
• If a key may have leaked, ask for it to be revoked right away, then replace it.

​

Rotate a key

​

Revoke a key

• Revocation takes effect on the very next request. There is no cache to wait for.
• It cannot be undone: a revoked key never works again. Request a new key if you still need access.
• The key record is kept for the audit trail of your dental clinic, and so are the creation and revocation events.

​

Authentication failures

{
  "type": "https://docs.muveya.com/errors/api_keys.invalid",
  "title": "API key invalid",
  "status": 401,
  "detail": "The API key is missing, malformed, revoked, or expired. Send a valid key as a Bearer token and try again.",
  "instance": "/v1/me",
  "code": "api_keys.invalid",
  "requestId": "8d0e5b8a-2f4c-4e1b-9a7d-0c3b5e6f7a81"
}

• The 401 is identical for every cause, on purpose: it does not reveal whether a key exists. Check the header format first, then check with the member who requested the key whether it was revoked or whether that member is still active.
• The 403 does not name the missing scope. Call GET /v1/me, compare the scopes with the table on Scopes, and request a key with the right scopes.
• Requests refused with 401 or 403 do not use your rate limit budget and carry no rate-limit headers.
• A record that belongs to another dental clinic answers 404, never 403.

​

MCP uses OAuth