Alya Books

    Help centre

    Guides for Alya Books and UAE e-invoicing

    العربية

    Why do I get 401 on API calls?

    Work through the reasons the Alya Books API rejects a request as unauthorized.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    A 401 UNAUTHORIZED means Alya Books could not accept the API key on the request. The message in the body names the exact reason; match it against the list below.

    Check the message

    MessageCauseFix
    Send your API key in the X-API-KEY headerNo key on the requestAdd the header X-API-KEY: sk_live_…. Authorization: Bearer sk_live_… also works.
    Malformed API keyThe value is not a Alya Books keyKeys look like sk_live_ or sk_test_ followed by 48 hex characters. Check for missing characters, quotes or spaces.
    Unknown API keyThe key does not existYou may have copied it wrongly, or it belongs to another Alya Books environment or organization. Create a new one.
    This API key was revokedSomeone clicked RevokeCreate a new key under API access.
    This API key has expiredThe expiry date set at creation has passedCreate a new key, with a later or no expiry.

    Step by step

    1. Go to API access → API keys and find the key by its prefix. The status column shows active, expired or revoked, and Last used tells you whether any call with it ever arrived.
    2. Open the Recent requests tab. If your call is not listed, the request did not reach Alya Books with a recognisable key: check the base URL shown on the Endpoint card.
    3. Run the copyable example from the Endpoint card with your key:
    curl <base>/me -H "X-API-KEY: sk_live_…"

    A 200 with your organization confirms the key; if the integration still fails, the problem is in how it sends the header.

    Not a 401?

    • 403 FORBIDDEN means the key works but lacks a scope, or X-Organization-Id names an organization your CA firm does not manage.
    • A 401 in the webhook deliveries dialog is the other direction: your server rejected Alya Books's delivery. Check your signature verification.

    Good to know

    • Keys are shown only once when created. Alya Books keeps a hash and cannot show the key again.
    • Owners and admins, or members with the "manage API keys" permission, can view and create keys.

    Still stuck? Contact support