Skip to content
All guides

Developers & devices

Connect Moazaf to your other systems with API keys and webhooks, and send punches from fingerprint machines.

Checked against the app on Wednesday, November 4, 2026

1. What this is for and who can use it

Most companies never need this page. Use it when another system must talk to Moazaf: your ERP, payroll or BI tool, or a fingerprint or face-recognition machine at the office door. There are three tools:

  • API keys: a key is like a password for another system. With it, that system can read or update data in Moazaf, for example the employee list.
  • Webhooks: Moazaf tells your other system when something happens, for example when a new employee is added or a document is about to expire.
  • Attendance devices: a fingerprint or face machine sends each check-in and check-out to Moazaf by itself.

  • API keys

    Where
    Settings › API & webhooks › API keys
    Who can do it
    Owner and Admin

  • Webhooks

    Where
    Settings › API & webhooks › Webhooks
    Who can do it
    Owner and Admin (or a custom role allowed to manage the API), only if their access is not limited to some companies, departments or categories

  • Attendance devices

    Where
    Attendance › Devices
    Who can do it
    Owner, Admin and HR Manager, if their access is not limited to some departments, and only for offices of companies they can manage

API keys and webhooks are part of the Business and Enterprise plans. On other plans the page shows API & webhooks aren't in your plan with a View plans button. If your plan drops API access, existing keys, webhooks and their deliveries stay viewable read-only and you can still revoke a key or delete a webhook, but you cannot add or change them and calls made with the keys are refused. Attendance devices need the Attendance module, which is also in the Business and Enterprise plans.

You will usually do the first step here (create the key or the device) and then hand the result to your IT team or your supplier. Send it to them in a safe way, never in a group chat or a shared email.

For HR and administrators

2. Create an API key

Settings › API & webhooks › API keys

A key always works as you. It can only do what you chose for it (its scopes), and never more than your own role allows. If your role cannot see salaries, a key you create cannot see them either.

  1. Open Settings and select API & webhooks. The API keys tab opens.
  2. Click Create API key.
  3. In Name, write where the key is used, for example Oracle ERP sync or Power BI dashboard.
  4. Optional: in Expires on, choose the last day the key may work. Leave it empty for a key that does not expire.
  5. Under Scopes, tick only what the other system needs. Each scope has a short explanation. Scopes your own role does not have are greyed out and marked not in your role.
  6. Click Create key.
The API keys tab with the Create API key button highlighted.
The Create API key form: a name, a last day, and the list of scopes with only the needed ones ticked.

Moazaf now shows the new key once. Click the copy button, store the key somewhere safe (for example your company password manager) and give it to the person who sets up the other system. Then click I've saved it.

The new key is shown once, with a copy button and a warning to store it safely. The key itself is blurred here.

Moazaf cannot show the key again. If you close the window without copying it, revoke that key and create a new one.

Give each system its own key with its own name. If one system is replaced or a key leaks, you can stop that one key without breaking the others.

For HR and administrators

3. Check and revoke keys

The API keys tab lists every key with its scopes, when it was Last used, when it Expires and its status: Active, Expired or Revoked.

  1. Find the key in the list.
  2. Click the bin icon (Revoke key) at the end of its row.
  3. Read the message and click Revoke key to confirm.

The key stops working at once. Any system still using it gets an error. This cannot be undone: to reconnect that system, create a new key.

  • A key also stops working when its last day has passed, when the person who created it is no longer an active member of the workspace, or when your plan no longer includes API access.
  • If someone who created keys leaves the company, create new keys under another admin before you remove that person, then revoke their old keys.
  • A workspace can have up to 50 active keys at the same time.

In the Expires column, the date shown is the moment the key stops working: the day after the last day you chose.

For HR and administrators

4. Where your IT team finds the API documentation

Settings › API & webhooks › API keys › Quick start

Under the list of keys, the Quick start box has everything a developer needs to begin. Send them these two things together with the key:

  • Base URL: the address every request starts with, for example https://app.moazaf.com/api/v1.
  • OpenAPI specification: the openapi.json link. It is the full technical list of what the API can do, and developer tools can read it directly.
The Quick start box with the base address, the openapi.json link (highlighted) and a sample request.

The box also shows how many requests per minute your plan allows. This limit is shared by all keys of the workspace. If a system sends too many requests, it is asked to wait and try again.

For HR and administrators

5. Send events to another system (webhooks)

Settings › API & webhooks › Webhooks

A webhook is an address on your other system (an endpoint) that Moazaf calls each time an event you chose happens. Your IT team gives you this address.

  1. Open the Webhooks tab and click Add endpoint.
  2. In Endpoint URL, paste the address from your IT team. It must start with https:// and be reachable from the internet.
  3. Optional: add a Description, for example Oracle HR: new joiners and leavers.
  4. Under Events, tick the events the other system needs, for example Employee created and Employee terminated. If you tick nothing, the endpoint receives every event you may see across the workspace. If you may see all data (like the Owner), new events added later are included too. A default Admin cannot see payroll, so for an Admin the endpoint is saved with every event except the payroll ones.
  5. Click Add endpoint.
  6. Moazaf shows a signing secret once. Copy it, give it to your IT team in a safe way, then click I've saved it.
The Webhooks tab with one active endpoint, its events and its last-24-hours counts.
The Add endpoint form with the address, a description and two People events ticked.

  • People

    Examples
    Employee created, updated, terminated, rehired

  • Documents

    Examples
    Document created, expiring, expired, renewed

  • Leave & requests

    Examples
    Leave requested, approved, rejected; request approved

  • Attendance

    Examples
    Punch recorded, late arrival, missing punch or absence

  • Payroll

    Examples
    Payroll approved, payroll closed (no salary amounts are sent)

  • Fleet, service desk, company and members

    Examples
    Vehicle assigned, ticket created, member joined and more

The signing secret lets your system check that a message really came from Moazaf. The Verifying deliveries box under the list explains this check for your IT team.

For HR and administrators

6. Test an endpoint and follow its deliveries

Each endpoint card shows its status (Active, Paused or Disabled) and how many deliveries succeeded, failed or are pending in the last 24 hours. The ⋯ menu on the card has everything else:

The endpoint menu, with Rotate signing secret highlighted.

  • Delivery log

    What it does
    Deliveries of the last 30 days for the events your role may see, with their status and the reply from your system. Open one to see what was sent, or click Redeliver to send it again.

  • Send test event

    What it does
    Sends a test message now, so your IT team can check that the endpoint works.

  • Edit

    What it does
    Change the address, description or events.

  • Rotate signing secret

    What it does
    Makes a new secret. Choose Rotate with a 24-hour overlap for a planned change, or Rotate and expire the old secret now if the old secret leaked.

  • Pause / Resume

    What it does
    Stops and restarts deliveries to this endpoint.

  • Delete

    What it does
    Removes the endpoint and its delivery log. This cannot be undone.

Your system must answer within 10 seconds. If it does not accept a delivery, Moazaf tries again automatically, waiting longer each time: up to 8 attempts in total (the first send and 7 retries) over about two days.

If 25 delivery attempts in a row fail (retries count, test events do not), Moazaf switches the endpoint to Disabled and notifies everyone who manages the API, inside the app. Ask your IT team to fix their system, use Send test event to check it, then choose Re-enable in the menu.

For HR and administrators

7. Connect a fingerprint or face machine

Attendance › Devices

A machine at the door can send every check-in and check-out to Moazaf by itself. You create a device secret in Moazaf, and your device supplier puts it in the machine (or in the small program that collects punches from it).

  1. Open Attendance and select the Devices tab.
  2. Click Add device.
  3. In Device name, write where the machine is, for example Main entrance reader.
  4. In Work centre / office, choose the office where the machine stands.
  5. Choose the Punch rule (see the table below), then click Save.
  6. Moazaf shows the secret once, with the address the machine must send to (/api/attendance/punches). Copy both and give them to your supplier in a safe way.
The Add device form: device name, office and punch rule.
After saving, the device secret is shown once with the sending instructions. The secret is blurred here.

  • Explicit in / out

    Use it when
    The machine has in and out buttons, or already knows which punch is which.

  • Alternate in / out (auto)

    Use it when
    The machine only records a punch. Moazaf records a punch as out if the employee's last punch was an in less than 24 hours earlier; otherwise it records it as in. Punches must arrive in time order.
The Devices tab with one active device and its Revoke credential button.

To stop a machine (lost, replaced or moved), click Revoke credential next to it and confirm. It stops at once. To reconnect it, add it again and give the supplier the new secret.

For HR and administrators

8. How punches from a machine arrive

  • Each punch carries the employee number. Moazaf matches it with the Employee no. on the employee profile, so the number in the machine must be exactly the same.
  • The office of the device must belong to the employee's own company. Punches for an employee of another company are refused.
  • If the machine sends a punch that already arrived, Moazaf ignores the copy, so a machine can safely send again after a network cut.
  • As soon as punches arrive, Moazaf works out the day again (present, late, absent or overtime) using the employee's schedule.

You see the punches in Attendance › Raw punches. In the Source column they show as Device API.

A device works with the permissions of the person who added it, and only that person sees it in the Devices tab. If that person leaves the workspace or loses their attendance permissions, the machine's punches are refused. Add the device again under another admin before that happens.

No connection from the machine? Export the punches from the machine as a file and upload it in Raw punches with Import CSV. The Attendance guide explains the file layout.

9. Common questions

  • I lost an API key. Can Moazaf show it again?

    Answer
    No. Moazaf never stores the key in a readable form. Revoke it and create a new one.

  • Why are some scopes greyed out?

    Answer
    Your own role does not have that right, and a key can never do more than you. For example, an Admin cannot give payroll scopes. Ask the Owner to create that key.

  • The Webhooks tab says webhooks need workspace-wide access.

    Answer
    Webhooks send data from every company in the workspace, so only someone allowed to manage the API (the Owner, an Admin or a custom role with that right) whose access is not limited to some companies, departments or categories can manage them.

  • Our endpoint shows Disabled. What happened?

    Answer
    Many delivery attempts in a row failed. Fix the receiving system, send a test event, then choose Re-enable in the endpoint menu. The Delivery log shows the error your system returned.

  • Can I see devices another admin added?

    Answer
    No. Each admin sees only the devices they added. Their machines keep working as long as that admin stays active with attendance permissions.

  • A machine's punches are not showing.

    Answer
    Check that the device is still Active in Devices, that the employee numbers in the machine match Employee no. in Moazaf, and that the device's office belongs to the employees' company. Then ask your supplier for the error the machine received.

  • Does Moazaf supply or install fingerprint machines?

    Answer
    No. Moazaf gives you the secret and the address; your device supplier connects the machine. For help, write to support@moazaf.com.

Still need help?

Email our support team. Tell us your company name and what you were trying to do.

support@moazaf.com
Developers & devices · Moazaf