> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erp.arukz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication: tokens and abilities

> Get an ARUKZ ERP API token by signing in with an email and password, choose read or read and write, and send it as a bearer token on every call.

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.

> [!TIP]
>
> 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

**1. 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](https://docs.erp.arukz.com/admin/users-and-roles.md). Every call is checked against that user's permissions.

**2. Sign in through the API**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "message": "Login successful",
  "token": "12|kQ3x...",
  "token_type": "Bearer",
  "user": { "id": 7, "name": "Reports", "email": "reports@yourcompany.in" }
}
```

**3. 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!NOTE]
>
> The [MCP server](https://docs.erp.arukz.com/ai/mcp.md) 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](https://docs.erp.arukz.com/admin/read-only-mode.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.