API authentication: tokens and abilities

You get an ARUKZ ERP API token by posting a user’s email and password to POST /admin/api/v1/login, and you send it on every other call as Authorization: Bearer <token>. The token acts as that user: same company, same role, same record visibility. It lasts 30 days, and you can ask for a read-only token for reporting tools.

The easiest way: a company admin opens Settings → API and AI access in the application, picks read-only or read and write, sets an optional expiry, and copies the token (shown once). The same page lists and revokes the company’s tokens. The steps below are for getting a token from a script.

Get a token

Pick the user the integration will act as

Use a real user of your company with only the role the integration needs. Your company’s admin creates users and roles under Settings → Users and Settings → Roles; see Users and roles. Every call is checked against that user’s permissions.

curl -X POST https://erp.arukz.com/admin/api/v1/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "reports@yourcompany.in", "password": "••••••••", "abilities": ["read"]}'

The answer holds the token:

{
  "message": "Login successful",
  "token": "12|kQ3x...",
  "token_type": "Bearer",
  "user": { "id": 7, "name": "Reports", "email": "reports@yourcompany.in" }
}

Keep the token secret

Store it where you keep other passwords. Anyone with the token can do what that user can do, until it expires.

Send the token

curl https://erp.arukz.com/admin/api/v1/sales/orders \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 12|kQ3x..."

Read, or read and write

The optional abilities field decides what the token may do:

`abilities`	The token may	Use it for
left out, or `["read", "write"]`	Read and change records	An integration that creates orders, posts receipts or updates products
`["read"]`	Only read (`GET`)	Reports, dashboards and other tools that never change data

A read-only token that sends POST, PUT, PATCH or DELETE gets 403. Signing out (POST /admin/api/v1/logout) works with either.

The MCP server for Claude, ChatGPT and other AI apps takes the same kind of token. Its tools only read, but an MCP app talks to it with POST requests, so give it a token with the default read and write abilities.

When a token stops working

After 30 days. Sign in again for a new one.
When you sign out with POST /admin/api/v1/logout, which revokes the token you send.
When the user’s password changes, or the user is deactivated. Every token of that user is revoked at once, so a leaked token does not outlive a password reset.
When the company is locked or read-only. An unpaid or suspended workspace gets 402 on every call; a read-only workspace can still read but gets 402 on writes. See Read-only mode.

Limits on signing in

Five sign-in attempts a minute from one address; the sixth gets 429.
Wrong credentials return 422 with The provided credentials are incorrect.
A user who signs in to the screens with two-factor authentication cannot get an API token, because the API sign-in has no second step. Create a separate user for the integration.

Get started

Endpoints

API authentication: tokens and abilities

Get a token

Send the token

Read, or read and write

When a token stops working

Limits on signing in